| 1 |
.. _inv: |
| 2 |
|
| 3 |
======================== |
| 4 |
``inv[oke]`` core usage |
| 5 |
======================== |
| 6 |
|
| 7 |
.. seealso:: |
| 8 |
This page documents ``invoke``'s core arguments, options and behavior |
| 9 |
(which includes options present in :ref:`custom Invoke-based binaries |
| 10 |
<reusing-as-a-binary>`). For details on invoking user-specified tasks and |
| 11 |
other parser-related details, see :doc:`/concepts/invoking-tasks`. |
| 12 |
|
| 13 |
|
| 14 |
Core options and flags |
| 15 |
====================== |
| 16 |
|
| 17 |
``invoke``'s usage looks like:: |
| 18 |
|
| 19 |
$ inv[oke] [--core-opts] task1 [--task1-opts] ... taskN [--taskN-opts] |
| 20 |
|
| 21 |
All core options & flags are below; almost all of them must be given *before* |
| 22 |
any task names, with a few (such as :option:`--help`) being specially looked |
| 23 |
for anywhere in the command line. (For parsing details, see |
| 24 |
:ref:`basic-cli-layout`.) |
| 25 |
|
| 26 |
.. option:: --complete |
| 27 |
|
| 28 |
Print (line-separated) valid tab-completion options for an Invoke command |
| 29 |
line given as the 'remainder' (i.e. after a ``--``). Used for building |
| 30 |
:ref:`shell completion scripts <tab-completion>`. |
| 31 |
|
| 32 |
For example, when the local tasks tree contains tasks named ``foo`` and |
| 33 |
``bar``, and when ``foo`` takes flags ``--foo-arg`` and ``--foo-arg-2``, |
| 34 |
you might use it like this:: |
| 35 |
|
| 36 |
# Empty input: just task names |
| 37 |
$ inv --complete -- |
| 38 |
foo |
| 39 |
bar |
| 40 |
|
| 41 |
# Input not ending with a dash: task names still |
| 42 |
$ inv --complete -- foo --foo-arg |
| 43 |
foo |
| 44 |
bar |
| 45 |
|
| 46 |
# Input ending with a dash: current context's flag names |
| 47 |
$ inv --complete -- foo - |
| 48 |
--foo-arg |
| 49 |
--foo-arg-2 |
| 50 |
|
| 51 |
For more details on how to make best use of this option, see |
| 52 |
:option:`--print-completion-script`. |
| 53 |
|
| 54 |
.. option:: --hide=STRING |
| 55 |
|
| 56 |
Set default value of run()'s 'hide' kwarg. |
| 57 |
|
| 58 |
.. option:: --no-dedupe |
| 59 |
|
| 60 |
Disable task deduplication. |
| 61 |
|
| 62 |
.. _print-completion-script: |
| 63 |
|
| 64 |
.. option:: --print-completion-script=SHELL |
| 65 |
|
| 66 |
Print a completion script for desired ``SHELL`` (e.g. ``bash``, ``zsh``, |
| 67 |
etc). This can be sourced into the current session in order to enjoy |
| 68 |
:ref:`tab-completion for tasks and options <tab-completion>`. |
| 69 |
|
| 70 |
These scripts are bundled with Invoke's distributed codebase, and |
| 71 |
internally make use of :option:`--complete`. |
| 72 |
|
| 73 |
.. _prompt-for-sudo-password: |
| 74 |
|
| 75 |
.. option:: --prompt-for-sudo-password |
| 76 |
|
| 77 |
Prompt at the start of the session (before executing any tasks) for the |
| 78 |
``sudo.password`` configuration value. This allows users who don't want to |
| 79 |
keep sensitive material in the config system or their shell environment to |
| 80 |
rely on user input, without otherwise interrupting the flow of the program. |
| 81 |
|
| 82 |
.. option:: --write-pyc |
| 83 |
|
| 84 |
By default, Invoke disables bytecode caching as it can cause hard-to-debug |
| 85 |
problems with task files and (for the kinds of things Invoke is typically |
| 86 |
used for) offers no noticeable speed benefit. If you really want your |
| 87 |
``.pyc`` files back, give this option. |
| 88 |
|
| 89 |
.. option:: -c STRING, --collection=STRING |
| 90 |
|
| 91 |
Specify collection name to load. |
| 92 |
|
| 93 |
.. option:: -d, --debug |
| 94 |
|
| 95 |
Enable debug output. |
| 96 |
|
| 97 |
.. option:: --dry |
| 98 |
|
| 99 |
Echo commands instead of actually running them; specifically, causes any |
| 100 |
``run`` calls to: |
| 101 |
|
| 102 |
- Act as if the ``echo`` option has been turned on, printing the |
| 103 |
command-to-be-run to stdout; |
| 104 |
- Skip actual subprocess invocation (returning before any of that machinery |
| 105 |
starts running); |
| 106 |
- Return a dummy `~invoke.runners.Result` object with 'blank' values (empty |
| 107 |
stdout/err strings, ``0`` exit code, etc). |
| 108 |
|
| 109 |
.. option:: -D, --list-depth=INT |
| 110 |
|
| 111 |
Limit :option:`--list` display to the specified number of levels, e.g. |
| 112 |
``--list-depth 1`` to show only top-level tasks and namespaces. |
| 113 |
|
| 114 |
If an argument is given to ``--list``, then this depth is relative; so |
| 115 |
``--list build --list-depth 1`` shows everything at the top level of the |
| 116 |
``build`` subtree. |
| 117 |
|
| 118 |
Default behavior if this is not given is to show all levels of the entire |
| 119 |
task tree. |
| 120 |
|
| 121 |
.. option:: -e, --echo |
| 122 |
|
| 123 |
Echo executed commands before running. |
| 124 |
|
| 125 |
.. option:: -f, --config |
| 126 |
|
| 127 |
Specify a :ref:`runtime configuration file <config-hierarchy>` to load. |
| 128 |
|
| 129 |
Note that you may instead use the ``INVOKE_RUNTIME_CONFIG`` environment |
| 130 |
variable in place of this option. If both are given, the CLI option will |
| 131 |
win out. |
| 132 |
|
| 133 |
.. option:: -F, --list-format=STRING |
| 134 |
|
| 135 |
Change the format used to display the output of :option:`--list`; may be |
| 136 |
one of: |
| 137 |
|
| 138 |
- ``flat`` (the default): single, flat vertical list with dotted task |
| 139 |
names. |
| 140 |
- ``nested``: a nested (4-space indented) vertical list, where each level |
| 141 |
implicitly includes its parent (with leading dots as a strong visual clue |
| 142 |
that these are still subcollection tasks.) |
| 143 |
- ``json``: intended for consumption by scripts or other programs, this |
| 144 |
format emits JSON representing the task tree, with each 'node' in the |
| 145 |
tree (the outermost document being the root node, and thus a JSON object) |
| 146 |
consisting of the following keys: |
| 147 |
|
| 148 |
- ``name``: String name of collection; for the root collection this is |
| 149 |
typically the module name, so unless you're supplying alternate |
| 150 |
collection name to the load process, it's usually ``"tasks"`` (from |
| 151 |
``tasks.py``.) |
| 152 |
- ``help``: First line of collection's docstring, if it came from a |
| 153 |
module; null otherwise (or if module lacked a docstring.) |
| 154 |
- ``tasks``: Immediate children of this collection; an array of objects |
| 155 |
of the following form: |
| 156 |
|
| 157 |
- ``name``: Task's local name within its collection (i.e. not the full |
| 158 |
dotted path you might see with the ``flat`` format; reconstructing |
| 159 |
that path is left up to the consumer.) |
| 160 |
- ``help``: First line of task's docstring, or null if it had none. |
| 161 |
- ``aliases``: An array of string aliases for this task. |
| 162 |
|
| 163 |
- ``default``: String naming which task within this collection, if any, |
| 164 |
is the default task. Is null if no task is the default. |
| 165 |
- ``collections``: An array of any sub-collections within this |
| 166 |
collection, members of which which will have the same structure as this |
| 167 |
outermost document, recursively. |
| 168 |
|
| 169 |
The JSON emitted is not pretty-printed, but does end with a trailing |
| 170 |
newline. |
| 171 |
|
| 172 |
.. option:: -h STRING, --help=STRING |
| 173 |
|
| 174 |
When given without any task names, displays core help; when given with a |
| 175 |
task name (may come before *or* after the task name) displays help for that |
| 176 |
particular task. |
| 177 |
|
| 178 |
.. option:: -l, --list=STRING |
| 179 |
|
| 180 |
List available tasks. Shows all tasks by default; may give an explicit |
| 181 |
namespace to 'root' the displayed task tree to only that namespace. (This |
| 182 |
argument may contain periods, as with task names, so it's possible to show |
| 183 |
only a small, deep portion of the overall tree if desired.) |
| 184 |
|
| 185 |
.. option:: -p, --pty |
| 186 |
|
| 187 |
Use a pty when executing shell commands. |
| 188 |
|
| 189 |
.. option:: -r STRING, --search-root=STRING |
| 190 |
|
| 191 |
Change root directory used for finding task modules. |
| 192 |
|
| 193 |
.. option:: -T INT, --command-timeout=INT |
| 194 |
|
| 195 |
Set a default command execution timeout of INT seconds. Maps to the |
| 196 |
``timeouts.command`` config setting. |
| 197 |
|
| 198 |
.. option:: -V, --version |
| 199 |
|
| 200 |
Show version and exit. |
| 201 |
|
| 202 |
.. option:: -w, --warn-only |
| 203 |
|
| 204 |
Warn, instead of failing, when shell commands fail. |
| 205 |
|
| 206 |
|
| 207 |
.. _tab-completion: |
| 208 |
|
| 209 |
Shell tab completion |
| 210 |
==================== |
| 211 |
|
| 212 |
Generating a completion script |
| 213 |
------------------------------ |
| 214 |
|
| 215 |
Invoke's philosophy is to implement generic APIs and then "bake in" a few |
| 216 |
common use cases built on top of those APIs; tab completion is no different. |
| 217 |
Generic tab completion functionality (outputting a shell-compatible list of |
| 218 |
completion tokens for a given command line context) is provided by the |
| 219 |
:option:`--complete` core CLI option described above. |
| 220 |
|
| 221 |
However, you probably won't need to use that flag yourself: we distribute a |
| 222 |
handful of ready-made wrapper scripts aimed at the most common shells like |
| 223 |
``bash`` and ``zsh`` (plus others). These scripts can be automatically |
| 224 |
generated from Invoke or :ref:`any Invoke-driven command-line tool |
| 225 |
<reusing-as-a-binary>`, using :option:`--print-completion-script`; the printed |
| 226 |
scripts will contain the correct binary name(s) for the program generating |
| 227 |
them. |
| 228 |
|
| 229 |
For example, the following command prints (to stdout) a script which works for |
| 230 |
``zsh``, instructs ``zsh`` to use it for the ``inv`` and ``invoke`` programs, |
| 231 |
and calls ``invoke --complete`` at runtime to get dynamic completion |
| 232 |
information:: |
| 233 |
|
| 234 |
$ invoke --print-completion-script zsh |
| 235 |
|
| 236 |
.. note:: |
| 237 |
You'll probably want to source this command or store its output somewhere |
| 238 |
permanently; more on that in the next section. |
| 239 |
|
| 240 |
Similarly, the `Fabric <https://fabfile.org>`_ tool inherits from Invoke, and |
| 241 |
only has a single binary name (``fab``); if you wanted to get Fabric completion |
| 242 |
in ``bash``, you would say:: |
| 243 |
|
| 244 |
$ fab --print-completion-script bash |
| 245 |
|
| 246 |
In the rest of this section, we'll use ``inv`` in examples, but please remember |
| 247 |
to replace it with the program you're actually using, if it's not Invoke |
| 248 |
itself! |
| 249 |
|
| 250 |
Sourcing the script |
| 251 |
------------------- |
| 252 |
|
| 253 |
There are a few ways to utilize the output of the above commands, depending on |
| 254 |
your needs, where the program is installed, and your shell: |
| 255 |
|
| 256 |
- The simplest and least disruptive method is to ``source`` the printed |
| 257 |
completion script inline, which doesn't place anything on disk, and will only |
| 258 |
affect the current shell session:: |
| 259 |
|
| 260 |
$ source <(inv --print-completion-script zsh) |
| 261 |
|
| 262 |
- If you've got the program available in your system's global Python |
| 263 |
interpreter (and you're okay with running the program at the startup of each |
| 264 |
shell session - Python's speed is admittedly not its strong point) you could |
| 265 |
add that snippet to your shell's startup file, such as ``~/.zshrc`` or |
| 266 |
``~/.bashrc``. |
| 267 |
- If the program's available globally but you'd prefer to *avoid* running an |
| 268 |
extra Python program at shell startup, you can cache the output of the |
| 269 |
command in its own file; where this file lives is entirely up to you and how |
| 270 |
your shell is configured. For example, you might just drop it into your home |
| 271 |
directory as a hidden file:: |
| 272 |
|
| 273 |
$ inv --print-completion-script zsh > ~/.invoke-completion.sh |
| 274 |
|
| 275 |
and then perhaps add the following to the end of ``~/.zshrc``:: |
| 276 |
|
| 277 |
source ~/.invoke-completion.sh |
| 278 |
|
| 279 |
But again, this is entirely up to you and your shell. |
| 280 |
|
| 281 |
.. note:: |
| 282 |
If you're using ``fish``, you *must* use this tactic, as our fish |
| 283 |
completion script is not suitable for direct sourcing. Fish shell users |
| 284 |
should direct the output of the command to a file in the |
| 285 |
``~/.config/fish/completions/`` directory. |
| 286 |
|
| 287 |
- Finally, if your copy of the needing-completion program is only installed in |
| 288 |
a specific environment like a virtualenv, you can use either of the above |
| 289 |
techniques: |
| 290 |
|
| 291 |
- Caching the output and referencing it in a global shell startup file will |
| 292 |
still work in this case, as it does not require the program to be |
| 293 |
available when the shell loads -- only when you actually attempt to tab |
| 294 |
complete. |
| 295 |
- Using the ``source <(inv --print-completion-script yourshell)`` approach |
| 296 |
will work *as long as* you place it in some appropriate per-environment |
| 297 |
startup file, which will vary depending on how you manage Python |
| 298 |
environments. For example, if you use ``virtualenvwrapper``, you could |
| 299 |
append the ``source`` line in ``/path/to/virtualenv/bin/postactivate``. |
| 300 |
|
| 301 |
Utilizing tab completion itself |
| 302 |
------------------------------- |
| 303 |
|
| 304 |
You've ensured that the completion script is active in your environment - what |
| 305 |
have you gained? |
| 306 |
|
| 307 |
- By default, tabbing after typing ``inv`` or ``invoke`` will display task |
| 308 |
names from your current directory/project's tasks file. |
| 309 |
- Tabbing after typing a dash (``-``) or double dash (``--``) will display |
| 310 |
valid options/flags for the current context: core Invoke options if no task |
| 311 |
names have been typed yet; options for the most recently typed task |
| 312 |
otherwise. |
| 313 |
|
| 314 |
- Tabbing while typing a partial long option will complete matching long |
| 315 |
options, using your shell's native substring completion. E.g. if no task |
| 316 |
names have been typed yet, ``--e<tab>`` will offer ``--echo`` as a |
| 317 |
completion option. |
| 318 |
|
| 319 |
- Hitting tab when the most recent typed/completed token is a flag which takes |
| 320 |
a value, will 'fall through' to your shell's native filename completion. |
| 321 |
|
| 322 |
- For example, prior to typing a task name, ``--config <tab>`` will |
| 323 |
complete local file paths to assist in filling in a config file. |