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
andbar
, and whenfoo
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
orinvoke
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.
- 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,
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.
- For example, prior to typing a task name,
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-taskArgument
objects),collection
(compiledCollection
of tasks, using defaults or core arguments affecting collection generation) andtasks
(a list ofParserContext
objects representing the requested task executions).
-
invoke.cli.
parse_gracefully
(parser, argv)¶ Run
parser.parse_argv(argv)
& gracefully handleParseError
.‘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.