Crazy-Complete Documentation

This documentation provides an overview of how to define shell completions for commands using crazy-complete.

Command Definition

To define a completion for a command, use the following structure:

prog: "<PROGRAM NAME>"
help: "<PROGRAM DESCRIPTION>"
options:
  <OPTION ...>
positionals:
  <POSITIONAL ...>

prog:

The name of the program for which you want to create completion.

help:

(optional) A short description of the program.

options:

(optional) A list of options the program accepts.

positionals:

(optional) A list of positional arguments the program uses.

Example:

prog: "git"
help: "Distributed version control system"

Option Definition

Options are defined as follows:

options:
  - option_strings: ["<OPTION STRING>", ...]
    metavar: "<METAVAR>"
    help: "<OPTION DESCRIPTION>"
    optional_arg: <BOOL>
    complete: <COMPLETE ACTION>
    repeatable: <BOOL>
    final: <BOOL>
    hidden: <BOOL>
    groups: ["<GROUP>", ...]
    when: "<CONDITION>"

option_strings:

A list of option strings (e.g., ["-h", "--help"]).

metavar:

(optional) The placeholder used for the argument (e.g., FILE).

help:

(optional) A description of the option.

optional_arg:

(optional) Indicates if the option’s argument is optional (default: false).

complete:

(optional) Defines the completion method. If not set, the option does not take an argument. Use ["none"] if the option accepts an argument but no specific completion method applies.

repeatable:

(optional) Whether an option can be used multiple times (default: false).

final:

(optional) If true, no further options are suggested after this one. Commonly used for --help or --version (default: false).

hidden:

(optional) Excludes this option from completion suggestions, but it remains valid when typed manually.

groups:

(optional) Assigns this option to one or more groups. Multiple options from the same group cannot be suggested at once, useful for mutually exclusive flags.

when:

(optional) Enables this option only if the condition evaluates to true.

Example:

options:
  - option_strings: ["--directory", "-C"]
    metavar: "PATH"
    help: "Run as if git was started in PATH"
    complete: ["directory"]

Positional Arguments

Positional arguments are defined as follows:

positionals:
  - number: <NUMBER>
    metavar: "<METAVAR>"
    help: "<POSITIONAL DESCRIPTION>"
    repeatable: <BOOL>
    complete: <COMPLETE ACTION>
    when: "<CONDITION>"

number:

The order of the positional argument (e.g., 1 for the first argument).

metavar:

(optional) Placeholder for the positional argument in the help text.

help:

(optional) A description of the positional argument.

repeatable:

(optional) Whether this argument can be repeated (default: false).

complete:

(optional) Completion method to generate possible values (default: ["none"]).

when:

(optional) Enables this positional only if the condition evaluates to true.

Example:

positionals:
  - number: 1
    metavar: "FILE"
    help: "File to process"
    complete: ["file"]

Subcommands

Subcommands are defined by appending them to the program name:

prog: "<PROGRAM NAME> <SUBCOMMAND> ..."
aliases: ["<ALIAS>", ...]
help: "<SUBCOMMAND DESCRIPTION>"

prog:

The name of the program, followed by the subcommand(s).

aliases:

(optional) A list of alternative names for the subcommand. Aliases must not include the program name.

help:

(optional) A description of the subcommand.

Example:

prog: "kubectl get"
help: "Display one or many resources"
options:
  - option_strings: ["--output"]
    complete: ["choices", ["json", "yaml", "wide"]]

Best Practices

• Use ["none"] only when a value is required but no completion applies.

• Use repeatable: true for options like --tag or --define.

• Set final: true for options like --help or --version so no further suggestions appear afterward.

• Use groups for mutually exclusive flags to improve user experience.