Guide · Open source
How to use urfave/cli: build Go command line tools
Updated · written with AI from the project's own documentation and checked against our catalogue data
urfave/cli is a Go package for building command line programs. It takes care of the tedious parts, such as parsing flags, organizing subcommands, generating help text and providing tab completion. This guide is for people who write Go and want to build a command line tool with that package.
urfave/cliurfave/cli · ★ 24.3k · MIT Install options & downloads Quick start
- 1Check that Go is installed. urfave/cli needs Go. Make sure Go is available on your machine before continuing.
- 2Add the module. Run go get github.com/urfave/cli/v3 inside your Go project directory.
- 3Describe your commands. Define the commands, subcommands and flags your tool needs, using the package's declarative structure.
- 4Add environment or file lookups. Where useful, let flags read values from environment variables or files, using urfave/cli-altsrc for structured file formats.
- 5Set up shell completion. Enable completion for bash, zsh, fish or PowerShell, following the hosted documentation for your shell.
- 6Generate docs if needed. Use urfave/cli-docs to produce man page or Markdown documentation from your command definitions.
What urfave/cli is and who it is for
urfave/cli is a declarative, simple, fast package for building command line tools in Go. It is a library you add to your own program, not a finished application you run directly.
It fits Go developers writing a tool with subcommands and flags, and teams that want shell completion for bash, zsh, fish or PowerShell without writing it themselves. It is not a fit if you do not write Go, or if you need a finished end-user program.
- Commands and subcommands, with alias and prefix match support
- Flags for simple types, slices, time, duration and others
- Compound short flags, so -a -b -c can be written -abc
- Help system and dynamic shell completion
- No dependencies beyond the Go standard library
Install urfave/cli in a Go project
You need Go installed. Then add the module to your Go project with the command from the project README. The module path is the v3 version of the package.
Run the command inside your project directory, where your Go module is set up.
go get github.com/urfave/cli/v3Define commands, subcommands and flags
urfave/cli is declarative: you describe your commands, subcommands and flags as data, and the package parses the command line against that description. Commands can have aliases, and the package also supports prefix matching.
Flags can read their values from environment variables, plain text files, or structured file formats through the separate urfave/cli-altsrc module.
- Use aliases on commands if you want short alternative names
- Attach flags to the command they belong to
- Load flag values from environment variables when users should not type them each time
Use help text and shell completion
The package generates help text from your command definitions, so users can see available commands and flags without you writing the help by hand.
Dynamic shell completion is provided for bash, zsh, fish and powershell. The README does not give the setup steps for each shell, so check the hosted documentation at https://cli.urfave.org for those details.
Generate man page and Markdown docs
Documentation can be generated in man and Markdown formats. This is supported through the urfave/cli-docs module, which is separate from the core package.
Reduce binary size with a build tag
If a small binary matters more to you than template customization, the urfave_cli_no_template build tag renders the default help and fish completion without text/template. The output stays the same, but help templates can no longer be customized. If you use a custom help template with the default printer, the program panics, so check this before you rely on the tag.
Replacing cli.HelpPrinter still works, but it receives "root", "command" or "subcommand" instead of the default template text.
go build -tags urfave_cli_no_templateWhat people use it for
- A Go developer building a tool with subcommands such as init, build and deploy, each with its own flags
- A team giving its internal command line tool tab completion in bash, zsh, fish or PowerShell
- A tool that reads API keys or settings from environment variables or config files
- A project that publishes man pages or Markdown reference docs generated from its command definitions
Frequently asked questions
Is urfave/cli free to use?
Yes. urfave/cli is released under the MIT licence, as stated in the project's LICENSE file. Check that file for the full terms.
What do I need to install urfave/cli?
You need Go installed. Then run go get github.com/urfave/cli/v3 inside your Go project.
Does urfave/cli have dependencies?
The README says it has no dependencies beyond the Go standard library.
Does urfave/cli support shell completion?
Yes. The README lists dynamic shell completion for bash, zsh, fish and powershell. The hosted documentation at cli.urfave.org covers setup.
How does urfave/cli compare to cobra or flag?
The source lists cobra, kingpin, urfave/cli v2 and the standard flag package as comparable projects, but it does not compare them feature by feature. Compare them against your own needs before choosing.
Where do I get help if something does not work?
The README points to the Q&A discussions on GitHub for questions, and to the issue tracker for bugs and feature requests. It notes that the project is run by unpaid volunteers.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use urfave/cli if you write Go and want a well-structured way to build a command line tool with subcommands, flags, help text and shell completion. Pick something else if you do not write Go, or if you want a ready-made end-user program rather than a library.
Install options & downloads