cli

See also

This page documents the invoke command-line program itself. For background on how parsing works, please see Command-line parsing. For details on task execution, see Task execution.

inv[oke] command-line program

One of the main ways to use Invoke is via its command-line program, which can load task modules and execute their tasks, optionally with flags for parameterization.

invoke‘s usage looks like:

$ inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts]

The core options (which must be given before any task names) are as follows:

--complete

Print (line-separated) valid tab-completion options for an Invoke command line given as the ‘remainder’ (i.e. after a --). Used for building shell completion scripts.

For example, when the local tasks tree contains tasks named foo and bar, and when foo takes flags --foo-arg and --foo-arg-2, you might use it like this:

# Empty input: just task names
$ inv --complete --
foo
bar

# Input not ending with a dash: task names still
$ inv --complete -- foo --foo-arg
foo
bar

# Input ending with a dash: current context's flag names
$ inv --complete -- foo -
--foo-arg
--foo-arg-2

For more details on how to use this option, see the bundled completion scripts stored in completion/ in the source distribution.

--no-dedupe

Disable task deduplication.

-c STRING, --collection=STRING

Specify collection name to load.

-d, --debug

Enable debug output.

-e, --echo

Echo executed commands before running. Requires contextualized tasks.

-f, --config

Specify a runtime configuration file to load.

-h STRING, --help=STRING

Show core or per-task help and exit.

-H STRING, --hide=STRING

Set default value of run()’s ‘hide’ kwarg.

-l, --list

List available tasks.

-p, --pty

Use a pty when executing shell commands. Requires contextualized tasks.

-r STRING, --root=STRING

Change root directory used for finding task modules.

-V, --version

Show version and exit.

-w, --warn-only

Warn, instead of failing, when shell commands fail. Requires contextualized tasks.

Shell tab completion

Invoke ships with some shell completion scripts, which leverage a core CLI mechanism suitable for use in custom completion scripts as well. If you’re using Bash or Zsh, simply do the following:

  • Obtain the source distribution, or visit the /completion/ folder on Github, and place a copy of the appropriate file (e.g. /completion/bash for Bash users) somewhere on your local system.

  • source the file in your shell login file (e.g. .bash_profile, .zshrc).

  • By default, tabbing after typing inv or invoke will display task names from your current directory/project’s tasks file.

  • Tabbing after typing a dash (-) or double dash (--) will display valid options/flags for the current context: core Invoke options if no task names have been typed yet; options for the most recently typed task otherwise.

    • Tabbing while typing a partial long option will complete matching long options, using your shell’s native substring completion. E.g. if no task names have been typed yet, --e<tab> will offer --echo as a completion option.
  • Hitting tab when the most recent typed/completed token is a flag which takes a value, will ‘fall through’ to your shell’s native filename completion.

    • For example, prior to typing a task name, --config <tab> will complete local file paths to assist in filling in a config file.

The internal cli module’s API docs

Potentially useful if you need to make your own command-line tool instead of using invoke directly.

invoke.cli.make_config(args, collection)

Generate a Config object initialized with parser & collection data.

Specifically, parser-level flags are consulted (typically as a top-level “runtime overrides” dict) and the Collection object is used to determine where to seek a per-project config file.

This object is then further updated within Executor with per-task configuration values and then told to load the full hierarchy (which includes config files.)

invoke.cli.parse(argv, collection=None, version=None)

Parse argv list-of-strings into useful core & per-task structures.

Returns:Three-tuple of args (core, non-task Argument objects), collection (compiled Collection of tasks, using defaults or core arguments affecting collection generation) and tasks (a list of ParserContext objects representing the requested task executions).
invoke.cli.parse_gracefully(parser, argv)

Run parser.parse_argv(argv) & gracefully handle ParseError.

‘Gracefully’ meaning to print a useful human-facing error message instead of a traceback; the program will still exit if an error is raised.

If no error is raised, returns the result of the parse_argv call.

invoke.cli.print_columns(tuples)

Print tabbed columns from (name, help) tuples.

Useful for listing tasks + docstrings, flags + help strings, etc.