{"id":13482551,"url":"https://github.com/j8r/clicr","last_synced_at":"2025-04-15T00:31:24.861Z","repository":{"id":152029256,"uuid":"130611952","full_name":"j8r/clicr","owner":"j8r","description":"A simple declarative command line interface builder","archived":false,"fork":false,"pushed_at":"2020-10-28T21:41:04.000Z","size":44,"stargazers_count":30,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-28T12:37:44.189Z","etag":null,"topics":["cli","crystal"],"latest_commit_sha":null,"homepage":"","language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/j8r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2018-04-22T22:10:27.000Z","updated_at":"2024-11-30T02:35:28.000Z","dependencies_parsed_at":"2023-09-13T21:51:49.333Z","dependency_job_id":null,"html_url":"https://github.com/j8r/clicr","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j8r%2Fclicr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j8r%2Fclicr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j8r%2Fclicr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j8r%2Fclicr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/j8r","download_url":"https://codeload.github.com/j8r/clicr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248984231,"owners_count":21193712,"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","crystal"],"created_at":"2024-07-31T17:01:03.158Z","updated_at":"2025-04-15T00:31:24.602Z","avatar_url":"https://github.com/j8r.png","language":"Crystal","funding_links":[],"categories":["Cli Builders","CLI Builders"],"sub_categories":[],"readme":"# Clicr\n\n[![Build Status](https://cloud.drone.io/api/badges/j8r/clicr/status.svg)](https://cloud.drone.io/j8r/clicr)\n[![ISC](https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square)](https://en.wikipedia.org/wiki/ISC_license)\n\nCommand Line Interface for Crystal\n\nA simple Command line interface builder which aims to be easy to use.\n\n## Installation\n\nAdd the dependency to your `shard.yml`:\n\n```yaml\ndependencies:\n  clicr:\n    github: j8r/clicr\n```\n\n## Features\n\nThis library uses generics, thanks to Crystal's powerful type-inference, and few macros, to provide this following advantages:\n\n- Compile time validation - methods must accept all possible options and arguments \n- No possible double commands/options at compile-time\n- Declarative `NamedTuple` configuration\n- Customizable configuration - supports all languages (See [Clicr.new](src/clicr.cr) parameters)\n- Fast execution, limited runtime\n\n## Usage\n\n### Simple example\n\n```crystal\nrequire \"clicr\"\n\nClicr.new(\n  label: \"This is my app.\",\n  commands: {\n    talk: {\n      label:      \"Talk\",\n      action:    {\"CLI.say\": \"t\"},\n      arguments: %w(directory),\n      options:   {\n        name: {\n          label:   \"Your name\",\n          default: \"foo\",\n        },\n        no_confirm: {\n          short: 'y',\n          label:  \"Print the name\",\n        },\n      },\n    },\n  },\n).run\n\nmodule CLI\n  def self.say(arguments, name, no_confirm)\n    puts arguments, name, no_confirm\n  end\nend\n```\n\nExample of commands:\n```\n$ myapp --help\nUsage: myapp COMMANDS [OPTIONS]\n\nMyapp can do everything\n\nCOMMANDS\n  t, talk   Talk\n\nOPTIONS\n  --name=foo         Your name\n  -y, --no-confirm   Print the name\n\n'myapp --help' to show the help.\n```\n```\n$ myapp talk /tmp name=bar\nno, bar in /tmp\n```\n```\n$ myapp talk home name=bar -y\nyes, bar in home\n```\n```\n$ myapp talk test\nno, foo in test\n```\n\n### Advanced example\n\nSee the  one in the [spec test](spec/clicr_spec.cr)\n\n### CLI Composition\n\nIt's also possible to merge several commands or options together.\n\n```crystal\nother = {\n  pp: {\n    label: \"It pp\",\n    action: \"pp\"\n  }\n}\n\nClicr.new(\n  label: \"Test app\",\n  commands: {\n    puts: {\n      alias: 'p',\n      label: \"It puts\",\n      action: \"puts\",\n    }.merge(other) \n  }\n)\n```\n\nHelp output:\n```\nUsage: myapp COMMAND\n\nTest app\n\nCOMMAND\n  p, puts   It puts\n  pp        It pp\n\n'myapp --help' to show the help.\n```\n\n## Reference\n\n### Commands\n\nExample: `s`, `start`\n\n```crystal\ncommands: {\n  short: {\n    action: { \"say\": \"s\" },\n    label: \"Starts the server\",\n    description: \u003c\u003c-E.to_s,\n    This is a full multi-line description\n    explaining the command\n    E,\n  }\n}\n```\n\n* `action` is a `NamedTuple` with as key the method to call, and as a value a command alia, which can be empty for none.\n* in `action`, parentheses can be added to determine the arguments placement, like `File.new().file`\n* `label` is supposed to be short, one-line description\n* `description` can be a multi-line description of the command. If not set, `label` will be used. \n\n### Arguments\n\nExample: `command FooBar`, `command mysource mytarget`\n\n```crystal\narguments: %w(directory names)\n```\n\n```crystal\narguments: {\"source\", \"target\"}\n```\n\n* if a `Tuple` is given, the arguments number **must** be exactly the `Tuple` size.\n* if an `Array` is given, the arguments number must be at least, or more, the `Array` size\n\n### Options\n\n#### Boolean options\n\nExample: `-y`, `--no-confirm`\n\n```crystal\noptions: {\n  no_confirm: {\n    short: 'y',\n    label: \"No confirmations\",\n  }\n}\n```\n\n* `short` creates a short alias of one character - must be a `Char`\n* concatenating single characters arguments like `-Ry1` is possible\n* dashes `-`, being invalid named arguments, will be replaced by `_` when calling the action method.\n\nSpecial case: the `help_option`, which is set to `\"help\"` with the options `-h, --help` by default,\nshows the help of the current (sub)command\n\n#### String options\n\nExample: `--name=foo`, or `--name foo`\n\n```crystal\noptions: {\n  name: {\n    label: \"This is your name\",\n    default: \"Foobar\",\n  }\n}\n```\n\n* an optional `default` value can be set.\n* if a `default` is not set, a `type` can be defined to cast from a given type, instead of a raw `String`. For example, `type: Int32` will call `Int32.new`.\n* can only be `String` (because arguments passed as `ARGV` are `Array(String)`) - if others type are needed, the cast must be done after the `action` method call\n\n## License\n\nCopyright (c) 2020 Julien Reichardt - ISC License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj8r%2Fclicr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fj8r%2Fclicr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj8r%2Fclicr/lists"}