Writing completions

Define completions with a JSON manifest and optional Rush provider functions:

name.json

Command tree, options, arguments, and provider references.

name.rush

Optional provider functions used by { "function": "..." } manifest providers.

Rush loads files lazily for the command being completed. Completion search directories include Rush data directories and user configuration directories; system/data completions load before user configuration completions. Put user completions in $XDG_CONFIG_HOME/rush/completions, or ~/.config/rush/completions when XDG_CONFIG_HOME is unset.

Set priority on commands, options, or static enum values to rank candidates. Use signed 8-bit values: 0 is default, positive values promote, and negative values derank fallback candidates.

Minimal static completion

{
  "$schema": "https://rush.horse/completion/schema/v1.schema.json",
  "manifestVersion": 1,
  "command": {
    "name": "tool",
    "subcommands": [
      { "name": "build", "description": "build the project" },
      { "name": "test", "description": "run tests" }
    ],
    "options": [
      { "long": "directory", "value": { "name": "path", "provider": "builtin.directories" } }
    ]
  }
}

Providers

{ "values": [...] }

Static enum candidates embedded in the manifest.

{ "builtin": "files" }

Built-in path completion for files and directories.

{ "builtin": "directories" }

Built-in path completion restricted to directories.

{ "builtin": "executables" }

Command-name completion from loaded functions, autoloadable functions, builtins, and PATH.

{ "builtin": "variables" }

Shell variable-name completion.

{ "builtin": "aliases" }

Shell alias-name completion.

{ "builtin": "jobs" }

Shell job-spec completion for job-control builtins.

{ "builtin": "functions" }

Shell function-name completion, including autoloadable functions that have not been sourced yet.

{ "function": "name" }

Run a Rush function in a hidden completion worker and collect candidates emitted by rush_complete.

Dynamic provider functions

Reference a function from the manifest:

{
  "providers": {
    "tool.targets": { "function": "__rush_complete_tool_targets" }
  },
  "arguments": {
    "states": [
      { "name": "target", "index": 0, "provider": "tool.targets" }
    ]
  }
}

Then define it in tool.rush:

__rush_complete_tool_targets() {
  tool list-targets 2>/dev/null |
    while read target; do
      test -n "$target" && rush_complete candidate "$target" --kind plain --description target
    done
}

Function providers run hidden with captured output and cloned shell state. Keep them read-only: Rush may cancel, supersede, or rerun them while the user edits. Emit best candidates first, and use rush_complete candidate --priority N to rank them.

Completion context

__rush_complete_tool_values() {
  if rush_complete option-present --long all; then
    rush_complete candidate everything --kind plain
  fi

  first="$(rush_complete operand 0)"
  case "$first" in
    deploy) rush_complete candidate production --kind plain ;;
    *) rush_complete files ;;
  esac
}

Rush sets rush_completion_prefix, rush_completion_argument_index, rush_completion_options_terminated, and rush_completion_value_position while a provider runs. See rush_complete(1) for the full API.

SEE ALSO

Completion manifest schema, rush_complete(1), rush-builtins(7).