`generate completions` for system

Generate `extern` definitions, with completions, for an external command from its carapace spec, fish or zsh completions, man page or --help text.

Signature

> generate completions {flags} (command)

Flags

--source, -s {string}: Where to read the flags from: carapace, fish, zsh, man, help, or all of them merged. Required when the source text is piped in.

Parameters

command: The external command, or one of its subcommands such as "git status".

Input/output types:

input	output
nothing	string
string	string

Examples

Generate completions for git and load them at every startup.

> let dir = $nu.user-autoload-dirs | first; mkdir $dir; generate completions git | save --force ($dir | path join git.nu)

Generate completions for one subcommand from the command's own --help text.

> generate completions 'cargo build' --source help

Merge what every source knows about git into one module.

> generate completions git --source all

Read help text that is piped in.

> '  -s, --short   show status concisely' | generate completions 'git status' --source help
# Generated by `generate completions` from help text piped in.
# Flags that are not declared here still reach `git`. Arguments without a completer
# here are completed by the external completer in $env.config.completions.external.

@complete external
export extern "git status" [
    --short(-s)                    # show status concisely
]

Without --source, the sources are tried in the order carapace, fish, zsh, man, help, and the first one that knows any flags or subcommands is used. A man page lists no subcommands, and a source may list a subcommand without any of its flags, as fish's own completions for ouch do. So when man is used, or a source that lists a subcommand it knows nothing else about, and the command's --help lists subcommands, what help finds is merged in as with --source all. With --source all, every source that knows any is used and their commands and flags are merged, the earlier source winning when they disagree. A flag they disagree on taking a value is declared as a switch, and the comment above its extern names the sources on each side. carapace, fish and zsh know the whole tree of subcommands, and man gives the flags of the named command only. The help source runs the command with --help, then each subcommand that help lists, and theirs in turn, to read the whole tree. It runs a subcommand that way only when another source knows it, the --help of the command above it lists it along with a --help option, or it has a man page, as git's subcommands do, since a command that doesn't read --help first would run instead. launchctl's help lists reboot, but no --help option, so launchctl reboot --help isn't run.

The result is the text of a module of export extern definitions. Externs exist only once nushell has parsed them, so save the text to a file and load it with use or source, or save it in one of $nu.user-autoload-dirs to load it at startup. For use, name the file something other than the command, such as git-completions.nu: use names the module after the file, and a module can't export an extern with its own name.

Flag values and arguments the source lists, such as --color's always, never and auto, become completions. Values that fish or zsh compute become completer commands in the module when they translate to nushell: a command such as git for-each-ref ... refs/heads/, or a shared helper for users, groups, hosts, processes, commands, network interfaces or make targets. A tool built with cobra, such as gh, docker or kubectl, completes its own arguments through its __complete command. Any other extern gets @complete external, so an argument none of these covers is completed by the external completer set in $env.config.completions.external, when there is one.

Flags with an optional value (--color[=when]) and single-dash long options (-name) can't be declared in a signature. They are listed in the extern's description and still reach the command.