{"id":32171653,"url":"https://github.com/rzcastilho/do_it","last_synced_at":"2025-10-21T17:54:54.346Z","repository":{"id":54857379,"uuid":"307865237","full_name":"rzcastilho/do_it","owner":"rzcastilho","description":"Do It - Elixir Command Line Interface Library","archived":false,"fork":false,"pushed_at":"2025-06-04T20:55:49.000Z","size":498,"stargazers_count":91,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-14T16:12:06.997Z","etag":null,"topics":["cli","command-line-interface","command-line-tool","elixir"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rzcastilho.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-28T00:41:56.000Z","updated_at":"2025-09-26T12:22:16.000Z","dependencies_parsed_at":"2023-09-23T12:49:05.233Z","dependency_job_id":"48149bd0-f105-4446-b831-f77244f1da8b","html_url":"https://github.com/rzcastilho/do_it","commit_stats":{"total_commits":41,"total_committers":1,"mean_commits":41.0,"dds":0.0,"last_synced_commit":"ab1baf3ecc15ec3adc7edecfe2e6ff03ebaf3db9"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/rzcastilho/do_it","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rzcastilho%2Fdo_it","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rzcastilho%2Fdo_it/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rzcastilho%2Fdo_it/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rzcastilho%2Fdo_it/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rzcastilho","download_url":"https://codeload.github.com/rzcastilho/do_it/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rzcastilho%2Fdo_it/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280308482,"owners_count":26308492,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","command-line-interface","command-line-tool","elixir"],"created_at":"2025-10-21T17:54:53.192Z","updated_at":"2025-10-21T17:54:54.340Z","avatar_url":"https://github.com/rzcastilho.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/rzcastilho/do_it/workflows/CI/badge.svg)](https://github.com/rzcastilho/do_it/actions) [![Hex.pm](https://img.shields.io/hexpm/v/do_it.svg)](https://hex.pm/packages/do_it) [![Coverage Status](https://coveralls.io/repos/github/rzcastilho/do_it/badge.svg)](https://coveralls.io/github/rzcastilho/do_it) [![Documentation](https://img.shields.io/badge/documentation-gray)](https://hexdocs.pm/do_it/)\n\n# Do It\n\nElixir Command Line Interface Library.\n\nA library that helps to develop CLI tools with Elixir.\n\n## Installation\n\nThe package can be installed by adding `do_it` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:do_it, \"~\u003e 0.7\"}\n  ]\nend\n```\n\n## Usage\n\n**_Do It_** have two main components:\n\n  * `DoIt.Command` - represents a single command.\n  * `DoIt.MainCommand` - the entrypoint of the application where you declare all the commands, must be used as `main_module` in `escript` definition.\n\nThe commands `version` and `help` are automatic generated for the client.\n\nThe version number is obtained from `mix.exs` or option `version` in `MainCommand`.\n\nSo, if you have a client named `cli`, you can type `cli version` and `cli help` to get the version number and the list of commands respectively from the client.\n\n### MainCommand\n\nIt's the entrypoint of your CLI, it generates functions matching all declared commands in that module, delegating the call to the matched command.\n\nA `MainCommand` could be defined as follows:\n\n```elixir\ndefmodule HelloWorld do\n  use DoIt.MainCommand,\n    description: \"HelloWorld CLI\"\n\n  command(HelloWorld.Say)\n  command(HelloWorld.Template)\nend\n```\n\n### Command\n\nWe can define a new command as follows:\n\n```elixir\ndefmodule HelloWorld.Say do\n  use DoIt.Command,\n    description: \"Say something!!!\"\n\n  argument(:message, :string, \"Hello message\")\n\n  option(:template, :string, \"Message template\", alias: :t)\n\n  def run(%{message: message}, %{template: template}, _) do\n    hello(message, template)\n  end\n\n  def run(%{message: message}, _, %{config: %{\"default_template\" =\u003e template}}) do\n    hello(message, template)\n  end\n\n  def run(_, _, context) do\n    IO.puts(\"Pass a template s parameter or define a default template using template set command\")\n    help(context)\n  end\n\n  defp hello(message, template) do\n    IO.puts(EEx.eval_string(template, assigns: [message: message]))\n  end\nend\n\n```\n\nA `help` option is automatically added to the command to describe its usage.\n\n```shell\n$ ./hello_world say --help\n\nUsage: hello_world say [OPTIONS] \u003cmessage\u003e\n\nSay something!!!\n\nArguments:\n  message   Hello message\n\nOptions:\n      --help       Print this help\n  -t, --template   Message template\n```\n\nUse `DoIt.Command` and provide a required `description`, the command name is the module name, you can override that name using the `name` option.\n\n```elixir\ndefmodule Hello do\n  use DoIt.Command,\n    name: \"olleh\",\n    description: \"Useless hello command\"\n\n  ...\n\nend\n```\n\nYou can declare subcommands in a command to group them logically using the `subcommand` macro.\n\n```elixir\ndefmodule HelloWorld.Template do\n  use DoIt.Command,\n    description: \"Manage HelloWorld Template\"\n\n  subcommand(HelloWorld.Template.Set)\n  subcommand(HelloWorld.Template.Unset)\n  subcommand(HelloWorld.Template.Show)\nend\n```\n\n## Package\n\nThere are two ways to generate the binaries.\n\n- [escript](https://hexdocs.pm/mix/Mix.Tasks.Escript.Build.html)\n- [burrito-elixir](https://github.com/burrito-elixir/burrito)\n\n### escript\n\nTo generate an application using the escript, you have to add a `:escript` key with the `:main_module` option to your project properties in your `mix.exs` file.\n\nThe `:main_module` is the module that you defined as `DoIt.MainCommand`.\n\n```elixir\n...\n  def project do\n    [\n      app: :hello_world,\n      version: \"0.1.0\",\n      elixir: \"~\u003e 1.14\",\n      start_permanent: Mix.env() == :prod,\n      deps: deps(),\n      escript: [main_module: Cli]\n    ]\n  end\n...\n```\n\nBuild the binary running the mix task bellow.\n\n```shell\n$ mix escript.build\n==\u003e do_it\nCompiling 4 files (.ex)\nGenerated do_it app\n==\u003e hello_world\nCompiling 1 file (.ex)\nGenerated escript hello_world with MIX_ENV=dev\n```\n\nA binary with the application name will be generated in the project root.\n\n```shell\n$ ./hello_world help                                                                                                                                                     ─╯\n\nUsage: hello_world COMMAND\n\nMy useless CLI\n\nCommands:\n  say     Useless hello command\n```\n\n### burrito-elixir\n\nTo configure the application to use the `burrito-elixir` you have to add the `burrito-elixir` dependency in your project, add the `:mod` property in the `application` function, and the `:releases` key with the releases configuration to your project properties in you `mix.exs` file.\n\nThe `:mod` property value is the module that you defined as `DoIt.MainCommand`.\n\n```elixir\ndefmodule CoinGeckoCli.MixProject do\n  use Mix.Project\n\n  def project do\n    [\n      app: :coin_gecko_cli,\n      version: \"0.1.0\",\n      elixir: \"~\u003e 1.14\",\n      start_permanent: Mix.env() == :prod,\n      deps: deps(),\n      releases: releases()\n    ]\n  end\n\n  # Run \"mix help compile.app\" to learn about applications.\n  def application do\n    [\n      extra_applications: [:logger],\n      mod: {CoinGeckoCli, []}\n    ]\n  end\n\n  # Run \"mix help deps\" to learn about dependencies.\n  defp deps do\n    [\n      {:tesla, \"~\u003e 1.7\"},\n      {:jason, \"~\u003e 1.4\"},\n      {:do_it, \"~\u003e 0.4\"},\n      {:burrito, \"~\u003e 1.3\"},\n      {:tableize, \"~\u003e 0.1.0\"}\n    ]\n  end\n\n  def releases do\n    [\n      coin_gecko_cli: [\n        steps: [:assemble, \u0026Burrito.wrap/1],\n        burrito: [\n          targets: [\n            macos: [os: :darwin, cpu: :x86_64],\n            linux: [os: :linux, cpu: :x86_64],\n            windows: [os: :windows, cpu: :x86_64]\n          ],\n        ]\n      ]\n    ]\n  end\nend\n```\n\nGenerate the binaries using the mix task bellow, a binary of each target will be generated in the `burrito_out` folder of your root application.\n\n```shell\n$ MIX_ENV=prod mix release\n...\n...\n...\n$ cd burrito_out\n$ ls -c1                                                                                                                                                                 ─╯\ncoin_gecko_cli_linux\ncoin_gecko_cli_macos\ncoin_gecko_cli_windows\n\n$ ./coin_gecko_cli_linux help                                                                                                                                            ─╯\n\nUsage: coin_gecko_cli COMMAND\n\nCoinGecko CLI\n\nCommands:\n  list     List assets\n```\n\n## Auto-completion\n\n**_Do It_** provides comprehensive shell auto-completion support for bash, fish, and zsh shells. Auto-completion helps users discover available commands, subcommands, and options without needing to remember the exact syntax.\n\n### Features\n\n- **Command completion**: Complete command and subcommand names\n- **Option completion**: Complete option flags (`--help`, `-v`, etc.)\n- **Value completion**: Complete option values when allowed values are defined\n- **Context-aware**: Completions are context-sensitive based on the current command path\n- **Multi-shell support**: Generate completion scripts for bash, fish, and zsh\n\n### Built-in Completion Commands\n\nEvery Do It CLI automatically includes completion commands:\n\n```shell\n# Generate completion script for bash\nyour_cli completion bash\n\n# Generate completion script for fish\nyour_cli completion fish\n\n# Generate completion script for zsh\nyour_cli completion zsh\n\n# Show installation instructions\nyour_cli completion install bash\n\n# Internal completion command (used by shell scripts)\nyour_cli completion complete \u003cargs\u003e\n\n# Debug completion information\nyour_cli completion debug\n```\n\n### Installation\n\n#### Bash\n\nAdd to your `~/.bashrc`:\n```bash\neval \"$(your_cli completion bash)\"\n```\n\nOr install system-wide:\n```bash\nyour_cli completion bash | sudo tee /etc/bash_completion.d/your_cli\n```\n\n#### Fish\n\nInstall completion script:\n```bash\nyour_cli completion fish \u003e ~/.config/fish/completions/your_cli.fish\n```\n\n#### Zsh\n\nAdd to your `~/.zshrc`:\n```bash\neval \"$(your_cli completion zsh)\"\n```\n\nMake sure you have completion system initialized:\n```bash\nautoload -U compinit\ncompinit\n```\n\n### Using Mix Task\n\nYou can also generate completion scripts during development:\n\n```bash\n# Generate bash completion to stdout\nmix do_it.gen.completion --shell bash\n\n# Generate fish completion and save to file\nmix do_it.gen.completion --shell fish --output ~/.config/fish/completions/myapp.fish\n\n# Show installation instructions\nmix do_it.gen.completion --shell zsh --install\n\n# Specify main module explicitly\nmix do_it.gen.completion --shell bash --main-module MyApp.CLI\n```\n\n### Enhanced Option Support\n\nYou can enhance option completion by specifying allowed values:\n\n```elixir\ndefmodule MyApp.Deploy do\n  use DoIt.Command,\n    description: \"Deploy application\"\n\n  option(:environment, :string, \"Target environment\",\n    allowed_values: [\"dev\", \"staging\", \"prod\"])\n\n  option(:format, :string, \"Output format\",\n    allowed_values: [\"json\", \"yaml\", \"table\"])\n\n  def run(_args, _opts, _context), do: :ok\nend\n```\n\nWith this setup, typing `myapp deploy --environment \u003cTAB\u003e` will complete with `dev`, `staging`, or `prod`.\n\n## License\n\nDo It is released under the Apache License 2.0 - see the [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frzcastilho%2Fdo_it","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frzcastilho%2Fdo_it","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frzcastilho%2Fdo_it/lists"}