Completion manifest schema

This page documents the JSON shape of Rush completion manifests. The canonical machine-readable schema is:

https://rush.horse/completion/schema/v1.schema.json

The schema files and examples live under website/completion/schema/. This page is only a human-readable guide to that schema; the JSON Schema is the source of truth for validation. For an end-to-end authoring guide, see Writing completions.

Minimal shape

{
  "$schema": "https://rush.horse/completion/schema/v1.schema.json",
  "manifestVersion": 1,
  "command": {
    "name": "git"
  }
}

A manifest requires manifestVersion and command. manifestVersion must be 1. The root command requires name.

Command objects

A command object describes one command node. The root command and nested subcommands use the same shape.

{
  "name": string or non-empty string array,
  "aliases": array of additional names,
  "description": string,
  "priority": integer relevance hint,
  "hidden": boolean,
  "deprecated": boolean or string,
  "platforms": array of platform ids,
  "variantProbe": installed-variant probe,
  "variants": object of command overlays,
  "providers": object of named providers,
  "options": array of option objects,
  "optionGroups": array of option group objects,
  "arguments": argument model,
  "subcommands": array of command objects,
  "dynamicSubcommands": provider references,
  "dynamicOptions": provider references
}

Options and values

An option must define at least one spelling source: short, long, or spellings. Additional fields describe values, repeatability, visibility, platform gates, and relationships to other options.

{
  "short": "C",
  "long": "directory",
  "aliases": ["workdir"],
  "value": {
    "name": "path",
    "provider": "builtin.directories"
  },
  "repeatable": true,
  "priority": 10,
  "description": "run from path"
}

spellings is for literal option tokens that do not fit short or long sugar, such as single-dash long options or plus-prefixed toggles. value may be one value object or an array of value objects for multi-word option values.

priority is a signed 8-bit integer relevance hint accepted on commands, options, and static enum values. Higher values prefer a candidate among otherwise comparable matches; Rush still performs final query-aware ordering. Omit it for the default priority 0. Use small bands consistently: 1-9 for a slight preference, 10-49 for strong context, 50-99 for exceptional context such as the current branch or active target, and negative values are allowed specifically to derank fallback candidates.

Providers

Providers are reusable candidate sources referenced by options, arguments, and dynamic command or option slots. The schema accepts three provider shapes:

{ "function": "__rush_complete_git_branches" }
{ "builtin": "directories" }
{ "values": ["auto", "always", "never"] }

Static enum values may be strings or objects with value, display, description, tag, suffix, removableSuffix, priority, and noSpace. Higher priority values prefer a candidate among otherwise comparable matches; Rush still performs final query-aware ordering.

Provider references may be a single provider id, an inline provider object, or an ordered array of provider references.

Arguments

An argument model requires states. Each state requires name and may define an index, provider, grammar, repeatability, conditions, and transitions.

{
  "arguments": {
    "states": [
      {
        "name": "action",
        "index": 0,
        "provider": "tool.actions"
      },
      {
        "name": "name",
        "after": { "previousState": "action" },
        "repeatable": true,
        "provider": "tool.names"
      }
    ]
  }
}

A state with rest: "command-line" is a terminal rest state. The schema forbids combining that rest state with repeatable, provider, or grammar.

Conditions and value grammars

Conditions can combine all, any, and not, or test option presence, option absence, exact option values, terminator state, previous argument state, and argument count.

Value grammars describe structured option or argument values. The schema includes enum, list, key/value, path, and string grammar shapes. List and key/value grammars define separators and nested value descriptions.

Platforms and variants

platforms gates commands or options to known platform ids: darwin, linux, freebsd, openbsd, netbsd, dragonfly, windows, wasi, and haiku.

variantProbe requires args and matches. variants maps variant names to command overlays containing the same structural fields as a command except for identity metadata.

Examples

Valid and invalid schema examples are published beside the schema:

https://rush.horse/completion/schema/examples/git-slice.valid.json
https://rush.horse/completion/schema/examples/precommand.valid.json
https://rush.horse/completion/schema/examples/literal-spellings.valid.json
https://rush.horse/completion/schema/examples/bad-option-shape.invalid.json