Writing completions

Rush command completions use a structured manifest plus optional Rush provider functions:

name.json

Command tree, options, arguments, and provider references.

name.rush

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

Files are loaded lazily when completing that command. System completions load before user completions. User completions live in $XDG_CONFIG_HOME/rush/completions, or ~/.config/rush/completions when XDG_CONFIG_HOME is unset.

Manifest-authored commands, options, and static enum values may set priority as a signed 8-bit integer relevance hint. Higher values prefer a candidate among otherwise comparable matches; Rush still performs final query-aware ordering. Omit it for the default priority 0; prefer small bands such as 1-9 for slight preference, 10-49 for strong context, 50-99 for exceptional context, and negative values are allowed specifically to 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 functions, builtins, and PATH.

{ "builtin": "variables" }

Shell variable-name completion.

{ "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 asynchronously from the editor's point of view. Rush runs them hidden with captured output and cloned shell state, so slow providers do not block terminal drawing or leak output to the screen. Provider functions should be read-only and side-effect-free because they may be canceled, superseded, or invoked repeatedly while the user edits. Emit the best candidates first, and use rush_complete candidate --priority N with the same priority scale when a candidate should be preferred among otherwise comparable matches.

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
}

The variables rush_completion_argument_index, rush_completion_options_terminated, and rush_completion_value_position are set while a function provider runs. See rush_complete(1) for the complete provider API.

SEE ALSO

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