Completion manifest schema

Use this page as a guide. Validate manifests against the canonical schema:

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

Schema files and examples live under website/completion/schema/. For an 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

Use command objects for the root command and subcommands.

{
  "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,
  "inherit": false,
  "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.

inherit controls whether an option remains available below subcommands. Omit it for the engine default, or set it to false for options that only apply to the command object where they are defined.

priority is a signed 8-bit ranking hint. Omit it for 0. Use positive values to promote candidates and negative values to derank fallbacks.

Providers

Reference providers from options, arguments, and dynamic command or option slots. Use one of three shapes:

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

Built-in providers include files, directories, executables, variables, aliases, jobs, and functions.

Static enum values may be strings or objects with value, display, description, tag, suffix, removableSuffix, priority, and noSpace.

A provider reference may be a provider id, an inline provider object, or an ordered array of references.

Arguments

An argument model requires states. Each state requires name and may define 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 values: enum, list, key/value, path, and string. List and key/value grammars also define separators and nested values.

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

Examples live 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