index.md

Welcome to urfave/cli

urfave/cli is a declarative, simple, fast, and fun package for building command line tools in Go featuring:

• commands and subcommands with alias and prefix match support
• flexible and permissive help system
• dynamic shell completion for bash, zsh, fish, and powershell
• man and markdown format documentation generation
• input flags for simple types, slices of simple types, time, duration, and others
• compound short flag support (-a -b -c ➡️ -abc)
• input lookup from:
  • environment variables
  • plain text files
  • structured file formats supported via the urfave/cli-altsrc package

These are the guides for each major version:

• v3
• v2
• v1

In addition to the version-specific guides, these other documents are available:

• CONTRIBUTING
• CODE OF CONDUCT
• RELEASING

Installation

Using this package requires a working Go environment. See the install instructions for Go.

Go Modules are required when using this package. See the go blog guide on using Go Modules.

Using v2 releases

The v2 series is the recommended version for new development. Ongoing maintenance is done on the v2-maint branch which receives minor improvements, bug fixes, and security fixes.

go get github.com/urfave/cli/v2@latest

import (
  "github.com/urfave/cli/v2" // imports as package "cli"
)

Using alpha-level v3 releases

The latest pre-release in progress on the main branch is the v3 series which should be considered alpha-level with an unstable API. Occasional alpha tags are pushed to allow for limited stability without pinning to an arbitrary commit. Please see the v3 migration guide on using v3 if you are upgrading from v2

go get github.com/urfave/cli/v3@latest

import (
  "github.com/urfave/cli/v3" // imports as package "cli"
)

Using v1 releases

⚠️ The v1 series is receiving security fixes only via the v1-maint branch and should not be used in new development. Please see the v2 migration guide and feel free to open an issue or discussion if you need help with the migration to v2.

Supported platforms

cli is tested against multiple versions of Go on Linux, and against the latest released version of Go on OS X and Windows. This project uses GitHub Actions for builds. To see our currently supported go versions and platforms, look at the github workflow configuration.