Your team ships an internal CLI called `deploytool` that takes a few flags and then a subcommand. In zsh, how would you write a completion function for it, and how do you make zsh use that function for that command?

## The file and the tag line A zsh completion for a command is a single autoloadable function, conventionally in a file named after the function with a leading underscore. The first line is the registration directive compinit reads during its scan: ```bash #compdef deploytool ``` One file can serve several commands by listing them all on that line. Drop the file in any directory on `fpath` (before `compinit` runs), and Tab against `deploytool` calls your function. ## _arguments: describing the command line Almost every shipped zsh completion is built on `_arguments`. You give it a list of **specifications**, each describing one option or one positional argument, and it works out which one the cursor is on and offers the right matches. An option specification has three parts: an exclusion list, the option itself, and a bracketed description. ```bash '(-v --verbose)'{-v,--verbose}'[print each step]' ``` The leading parenthesised list says "once one of these is present, stop offering any of them" — that is how `_arguments` avoids suggesting `--verbose` when `-v` is already typed. The brace expansion is plain zsh, producing two specifications that share the same description. An option that takes a value adds colon-separated fields after the description: ```bash '--config=[path to config file]:config file:_files' ``` The pattern is `:message:action`. The message is what the user sees as the group heading; the action says how to generate candidates. Actions can be another completion function (`_files`, `_hosts`, `_users`), a literal list in parentheses, or a `->state` request. Positional arguments use a number instead of an option name — `'1:subcommand:->subcmd'` is the first positional — and `'*::args:->args'` collects everything after it. ## States: handling subcommands A subcommand-style CLI needs two phases: complete the subcommand name, then complete that subcommand's own arguments. `_arguments` supports this with the `->state` action, which does not generate matches itself but sets the `$state` parameter and returns, letting you decide: ```bash _arguments -s -C \ '1: :->subcmd' \ '*:: :->args' case $state in subcmd) _describe 'subcommand' subcmds ;; args) case $words[1] in apply) _arguments '--yes[do not prompt]' ;; esac ;; esac ``` `-s` allows single-letter options to be stacked (`-vf`); `-C` lets `_arguments` update `$curcontext` for the `->state` actions, so your inner completions get their own zstyle context. With `*::`, the double colon makes `$words` and `$CURRENT` be rewritten relative to the sub-command, so the nested `_arguments` sees a command line that starts at the subcommand — exactly what you want for per-subcommand flags. ## _describe: names with descriptions `_describe` takes a tag description and the name of an array of `value:description` strings: ```bash local -a subcmds subcmds=( 'plan:show what would change' 'apply:apply the pending changes' ) _describe 'subcommand' subcmds ``` The descriptions are shown alongside the candidates in the listing, which is the difference between a completion that merely saves typing and one that documents the tool while you use it. Where the values have no descriptions, `_values` or a literal action list `(plan apply)` is enough; `_alternative` combines several kinds of candidate at one point. ## Declaring locals Completion functions run in your interactive shell, so leaking parameters is a real hazard. The conventional preamble is: ```bash local curcontext="$curcontext" state line typeset -A opt_args ``` `$line` and `$opt_args` are populated by `_arguments` with the positional words and the options-with-values seen so far, which is how a later spec can depend on an earlier flag. ## compdef: binding without a file `compdef` is the runtime equivalent of the `#compdef` line. `compdef _deploytool deploytool` binds a function you already defined. The assignment form re-uses an existing completion for another name: `compdef dt=deploytool` makes a wrapper or alias complete like the original, and `compdef -d name` removes a binding. There is also `compdef _gnu_generic mytool`, which completes options by running the command's `--help` and parsing it — zero maintenance, option names only. ## Testing the loop Completion functions are autoloaded once per session, so editing the file does not affect the running shell. Either start a fresh shell, or re-source the function explicitly with `unfunction _deploytool && autoload -Uz _deploytool` before trying again — otherwise you will spend an hour debugging the version zsh loaded ten minutes ago.