{"id":22588518,"url":"https://github.com/evilmarty/ilc","last_synced_at":"2025-04-10T21:23:07.383Z","repository":{"id":38374105,"uuid":"485714750","full_name":"evilmarty/ilc","owner":"evilmarty","description":"A simple way to create a command-line utility","archived":false,"fork":false,"pushed_at":"2025-04-09T10:22:21.000Z","size":268,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T11:27:19.775Z","etag":null,"topics":["cli","config","go","golang","homebrew","utility"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evilmarty.png","metadata":{"files":{"readme":"README.md","changelog":"history.go","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"evilmarty"}},"created_at":"2022-04-26T09:17:07.000Z","updated_at":"2025-04-09T10:20:55.000Z","dependencies_parsed_at":"2024-07-16T12:32:36.136Z","dependency_job_id":"f7a15d67-4e83-40ac-ba49-42775b92a211","html_url":"https://github.com/evilmarty/ilc","commit_stats":{"total_commits":63,"total_committers":2,"mean_commits":31.5,"dds":0.3015873015873016,"last_synced_commit":"18ad01528b2b02dfa0ee49800e67013d8d836773"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmarty%2Filc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmarty%2Filc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmarty%2Filc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilmarty%2Filc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evilmarty","download_url":"https://codeload.github.com/evilmarty/ilc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248299161,"owners_count":21080475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","config","go","golang","homebrew","utility"],"created_at":"2024-12-08T08:09:46.571Z","updated_at":"2025-04-10T21:23:07.372Z","avatar_url":"https://github.com/evilmarty.png","language":"Go","funding_links":["https://github.com/sponsors/evilmarty"],"categories":[],"sub_categories":[],"readme":"![ILC](assets/logo.svg)\n\n# The simple way to create a command-line utility\n\n[![CI](https://github.com/evilmarty/ilc/actions/workflows/ci.yml/badge.svg)](https://github.com/evilmarty/ilc/actions/workflows/ci.yml) [![GitHub Release](https://img.shields.io/github/v/release/evilmarty/ilc)](https://github.com/evilmarty/ilc/releases/latest) ![GitHub License](https://img.shields.io/github/license/evilmarty/ilc)\n\nCreate an easy to use interactive CLI to simplify your workflow with a single\nYAML file.\n\n## Installation\n\n### Homebrew\n\nTo install via [Homebrew](https://brew.sh) just run the following command:\n\n```shell\nbrew install --cask evilmarty/ilc/ilc\n```\n\n### Golang\n\nEnsure you have [Go](https://go.dev) installed then run the follow:\n\n```shell\ngo install github.com/evilmarty/ilc\n```\n\n### Manual\n\nBinaries are available to download. Get the [latest release](https://github.com/evilmarty/ilc/releases/latest) binary for your platform.\n\n## Usage\n\nThe usage is as followed:\n\n```shell\nilc [--version] [--debug] CONFIG [COMMAND ...] [INPUT ...]\n```\n\n`CONFIG` is the path to your config file.\n\n`COMMAND` is one or a cascade of subcommands defined in the config file.\n\n`INPUT` is one or many inputs inherited by the command.\n\nThe best way to use `ilc` is to include it in the shebang of your config, like so:\n\n```yaml\n#!/usr/bin/env ilc\n```\n\n### Commands\n\nIf the configuration has defined `commands` they can either be passed as\narguments or an interactive prompt will allow you to choose a command. If the\ncommand specified in the arguments has itself subcommands the interactive\nprompt will appear to complete the selection process.\n\n### Inputs\n\nAfter a command is specified or selected an interactive prompt will ask for\ninput before the command will be executed. Inputs can be passed as arguments or\nas environment variables that are prefixed with `ILC_INPUT_`. Inputs that have\nbeen passed as arguments will not be asked, only for the inputs that have yet a value.\n\nAll inputs will also be accessible via environment variables prefixed with `ILC_INPUT_`.\n\n#### Example of passing inputs as arguments\n\n```shell\nilc example/ilc.yaml calendar -month feb\n```\n\n#### Example of passing inputs via environment variables\n\n```shell\nexport ILC_INPUT_month=feb\nilc example/ilc.yaml calendar\n```\n\n## Config\n\n### `description`\n\nThe overall description of what is the config's purpose. Is optional.\n\n### `env`\n\nOptionally set environment variables for the command. Cascades to descending\ncommands and subcommands. Expressions can be used in values.\n\n### `shell`\n\nThe shell to run the command in. Must be in JSON array format. Defaults to `[\"/bin/sh\"]`.\n\n### `run`\n\nRuns command-line programs using the specified shell. If `commands` is also\ndefined then `run` cannot be invoked directly and becomes a template accessible\nto all nested commands. See [Templating](#templating) for more information.\n\n### `pure`\n\nSetting `pure` to `true` to not pass through environment variables and only use\nenvironment variables that have been specified or inherited. Subcommands do not\ninherit this option and must be set for each command.\n\n### `inputs`\n\nOptionally specify inputs to be used in `run` and `env` values. Inputs can be\npassed as arguments or will be asked when invoking a command. Nested commands\ninherit inputs and cascade down.\n\n### `inputs.\u003cinput_name\u003e`\n\nThe key `input_name` is a string and its value is a map of the input's\nconfiguration. The name can be used as an argument in the form `-\u003cinput_name\u003e`\nor `--\u003cinput_name\u003e` followed by a value. The value can be omitted for boolean types.\n\n### `inputs.\u003cinput_name\u003e.type`\n\nThe type of input. Defaults to `string` but can also be `boolean` and `number`.\n\n### `inputs.\u003cinput_name\u003e.description`\n\nOptionally describe the input's purpose or outcome.\n\n### `inputs.\u003cinput_name\u003e.options`\n\nLimit the value to a list of acceptable values. Options can be a list of values\nor a map, with the keys presented as labels and the corresponding values the\nresulting value.\n\n#### Example of option types\n\n- A list of options:\n\n```yaml\ninputs:\n  month:\n    options:\n      - January\n      - February\n      - March\n      - April\n      - May\n      - June\n      - July\n      - August\n      - September\n      - October\n      - November\n      - December\n```\n\n- A map of options:\n\n```yaml\ninputs:\n  city:\n    options:\n      Brisbane: bne\n      Melbourne: mlb\n      Sydney: syd\n```\n\n### `inputs.\u003cinput_name\u003e.pattern`\n\nA regex pattern to validate the input's value. Default is to allow any input.\nApplies to `string` types only.\n\n#### Example setting an input pattern\n\n```yaml\ninputs:\n  year:\n    pattern: \"(19|20)[0-9]{2}\"\n```\n\n### `inputs.\u003cinput_name\u003e.default`\n\nSet the default value for the input. It is overwritten when a value is given as\nan argument or changed when prompted. If a default value is not defined then a\nvalue is required.\n\n### `inputs.\u003cinput_name\u003e.min`\n\nThe minimum value the input can be. Applies to `number` types only.\n\n### `inputs.\u003cinput_name\u003e.max`\n\nThe maximum value the input can be. Applies to `number` types only.\n\n### `commands`\n\nThe commands defined are then available to be invoked from the command line\neither by passing arguments or by interactive selection. Must define at least\none command.\n\n### `commands.\u003ccommand_name\u003e`\n\nUse `commands.\u003ccommand_name\u003e` to give your command a unique name. The key\n`command_name` is a string and its value is a map of the command's configuration\ndata. A string value can be used as a shorthand for the `run` attribute.\n\n#### Example defining an inline command\n\n```yaml\ncommands:\n  calendar: cal\n```\n\n### `commands.\u003ccommand_name\u003e.description`\n\nOptionally describe the command's purpose or outcome.\n\n### `commands.\u003ccommand_name\u003e.run`\n\nSee [`run`](#run) for more information.\n\n### `commands.\u003ccommand_name\u003e.commands`\n\nDefine sub-commands in the same structure as `commands`. All `inputs` or `env`\ndefined cascade to all sub-commands. Cannot be used in conjunction with `run`.\n\n### `commands.\u003ccommand_name\u003e.env`\n\nOptionally set environment variables for the command. Cascades to descending\ncommands and subcommands. See [Templating](#templating) for more information.\n\n#### Example of templating an environment variable\n\n```yaml\ncommands:\n  greet:\n    env:\n      NAME: \"{{ .Input.name }}\"\n      GREETING: Hello\n```\n\n### `commands.\u003ccommand_name\u003e.pure`\n\nSetting `pure` to `true` to not pass through environment variables and only use\nenvironment variables that have been specified or inherited. Subcommands do not\ninherit this option and must be set for each command.\n\n### `commands.\u003ccommand_name\u003e.inputs`\n\nOptionally specify inputs to be used in `run` and `env` values. Inputs can be\npassed as arguments or will be asked when invoking a command. Nested commands\ninherit inputs and cascade down. See [`inputs`](#inputs-1) for more information.\n\n### `commands.\u003ccommand_name\u003e.aliases`\n\nOptionally include additional aliases to reference the command. Aliases must be\nunique within the same parent.\n\n#### Example of defining aliases\n\n```yaml\ncommands:\n  files:\n    commands:\n      list:\n        aliases:\n          - ls\n        run: ls -lf\n  directories:\n    aliases:\n      - dir\n    commands:\n      list:\n        aliases:\n          - ls\n        run: ls -ld\n```\n\n## Templating\n\nGo's [template language](https://pkg.go.dev/text/template) is available for\n`run` and `env` values to construct complex entries. Templates are evaluated\nafter inputs are collected but before script execution. Along with inputs,\ntemplates can access environment variables that are present and regardless\nwhether `pure` is enabled or not.\n\nNested commands can include the run scripts from their parent commands.\nie. `{{template \"\u003ccommand_name\u003e\"}}`\n\n### .Input.\u003cinput_name\u003e\n\nThe expression to reference an input value. ie. '{{ .Input.my_input }}'\n\n### .Env.\u003cvariable_name\u003e\n\nThe expression to reference an environment variable. ie. '{{ .Env.HOME }}'\n\n### input \"input_name\"\n\nA function to retrieve the input by its name. ie. '{{input \"my_input\"}}'\n\n### env \"variable_name\"\n\nA function to retrieve the environment variable by its name. ie. '{{env \"HOME\"}}'\n\n## Example config with single command\n\n```yaml\ndescription: Display a calendar for the month\ninputs:\n  month:\n    options:\n      - January\n      - February\n      - March\n      - April\n      - May\n      - June\n      - July\n      - August\n      - September\n      - October\n      - November\n      - December\nrun: cal -m {{ .Input.month }}\n```\n\n## Example config with commands\n\n```yaml\ndescription: My awesome CLI\ncommands:\n  weather:\n    description: Show the current weather forecast\n    run: curl wttr.in?0QF\n  calendar:\n    description: Display a calendar for the month\n    inputs:\n      month:\n        options:\n          - January\n          - February\n          - March\n          - April\n          - May\n          - June\n          - July\n          - August\n          - September\n          - October\n          - November\n          - December\n    run: cal -m {{ .Input.month }}\n  greet:\n    description: Give a greeting\n    inputs:\n      name:\n        default: World\n      greeting:\n        options:\n          - Hello\n          - Hi\n          - G'day\n    run: echo $GREETING $NAME\n    env:\n      NAME: \"{{ .Input.name }}\"\n      GREETING: \"{{ .Input.greeting }}\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilmarty%2Filc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevilmarty%2Filc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilmarty%2Filc/lists"}