commands.get

One command by its canonical identity: its arguments with the source of each one's values, what running it changes, what it needs, where it came from, and every surface that carries it — with the reason a machine surface withholds it when one does.

query
implemented
module commands
#commands
#introspection

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_command
HTTP	GET /api/v1/command operationId commands.get
command line	—

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · CommandRequest

One command, by its canonical identity.

property	type	required	description
id	string	yes	The identity, `executable.worktree.status`.

JSON Schema

{
  "additionalProperties": false,
  "description": "One command, by its canonical identity.",
  "properties": {
    "id": {
      "description": "The identity, `executable.worktree.status`.",
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "title": "CommandRequest",
  "type": "object"
}

output · CommandNode

One command, from whichever program offers it.

property	type	required	description
aliases	array	no	Other names that resolve to this node, declared once here and honoured by every projection that has a use for one.
arguments	array	yes	The arguments, in declaration order.
availability	reference	yes	Where it means anything.
deprecation	one of 2	no	Whether this is still the name to use.
description	string \| null	no	The longer description, when the declaration carries one.
effect	reference	yes	What it changes.
entrypoint	boolean \| null	no	Is this command an entry point of its group — the one a newcomer is offered?
execution	reference	yes	How it is run.
group	string \| null	no	The group a person finds it under, when the declaration has groups.
id	reference	yes	The canonical identity.
interactivity	reference	yes	How it behaves towards a terminal.
invocation	string	yes	The command line a person types, rendered once here.
origin	reference	yes	Which program runs it.
path	array	yes	The words after the program's own name.
projections	reference	yes	Where it appears.
provenance	reference	yes	Where it came from.
runnable	boolean	yes	Can it be run on its own, or does it only group the commands under it?
stability	reference	yes	Where it stands.
summary	string	yes	One line.
tags	array	no	Free tags.

JSON Schema

{
  "$defs": {
    "CapabilityId": {
      "description": "A stable, globally meaningful identity: a namespace, a dot, and a local part.\n`repository.info` and `objects.get` for executables; `<kind>.<identity>` for a\ndeclarative object (`rule.majordomus.scope-integrity@1`, `document.docs/CLI.md`,\n`policy..ai/repo/policy.yaml`).\n\nGrammar: the namespace matches `[a-z][a-z0-9_-]*`; the local part is non-empty and\ncarries no whitespace or control character, any other Unicode included, because it is\nopaque: a path, a versioned identity, or a name, as the kind's identity rule produced it.",
      "type": "string"
    },
    "CommandArgument": {
      "description": "One argument of a command, as the declaration gives it plus what can be inferred.",
      "properties": {
        "defaults": {
          "description": "The defaults, as the declaration renders them.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "global": {
          "description": "Accepted by every command under the one that declares it.",
          "type": "boolean"
        },
        "help": {
          "description": "The help text, one line.",
          "type": "string"
        },
        "long": {
          "description": "`--long`, without the dashes.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The argument's id.",
          "type": "string"
        },
        "positional": {
          "description": "Given by position rather than by flag.",
          "type": "boolean"
        },
        "required": {
          "description": "Must be given.",
          "type": "boolean"
        },
        "secrecy": {
          "$ref": "#/$defs/CommandSecrecy",
          "description": "How openly the value may be handled."
        },
        "short": {
          "description": "`-s`, without the dash.",
          "maxLength": 1,
          "minLength": 1,
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "$ref": "#/$defs/CommandValueSource",
          "description": "Where further values come from."
        },
        "takes_value": {
          "description": "Takes a value at all; a flag does not.",
          "type": "boolean"
        },
        "value_name": {
          "description": "The placeholder, `PATH`.",
          "type": [
            "string",
            "null"
          ]
        },
        "values": {
          "description": "The values the declaration carries, each with its help.",
          "items": {
            "$ref": "#/$defs/CommandValueChoice"
          },
          "type": "array"
        },
        "variadic": {
          "description": "Takes any number of values.",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "positional",
        "takes_value",
        "required",
        "variadic",
        "global",
        "help",
        "source",
        "secrecy"
      ],
      "type": "object"
    },
    "CommandAvailability": {
      "description": "Where a command means anything, and why not when it does not.\n\nDerived from the repository environment rather than declared per command, so that a\nprojection reads a field instead of re-deciding. The reason is carried because the\nanswer a person needs is never `false`.",
      "properties": {
        "available": {
          "description": "Can it be run here, now?",
          "type": "boolean"
        },
        "reason": {
          "description": "Why not, in one line, when it cannot.",
          "type": [
            "string",
            "null"
          ]
        },
        "requires": {
          "description": "What it needs, whether or not that is satisfied here.",
          "items": {
            "$ref": "#/$defs/CommandRequirement"
          },
          "type": "array"
        }
      },
      "required": [
        "available"
      ],
      "type": "object"
    },
    "CommandDeprecation": {
      "description": "A command that is no longer the name to use.",
      "properties": {
        "reason": {
          "description": "Why, in one line.",
          "type": "string"
        },
        "replaced_by": {
          "anyOf": [
            {
              "$ref": "#/$defs/CommandId"
            },
            {
              "type": "null"
            }
          ],
          "description": "What to use instead."
        }
      },
      "required": [
        "reason"
      ],
      "type": "object"
    },
    "CommandEffect": {
      "description": "What running a command changes. The one thing a surface policy is allowed to ask.\n\nThe order is the order of increasing consequence, and it is the order the derived\nexposure policy reads: a surface declares the strongest effect it will carry, and\nevery node at or below it is projected there. Nothing configures a surface per\ncommand.",
      "oneOf": [
        {
          "const": "read_only",
          "description": "Reads and answers. Changes nothing anywhere.",
          "type": "string"
        },
        {
          "const": "local_mutation",
          "description": "Writes only where the repository keeps a checkout's own state — the process's\nmemory, `.ai/local/`, a build directory. Nothing a commit would carry.",
          "type": "string"
        },
        {
          "const": "repository_mutation",
          "description": "Writes tracked files: generated artifacts, the worktree, git itself.",
          "type": "string"
        },
        {
          "const": "network_mutation",
          "description": "Reaches the network with an effect on the far side: a push, a deploy, a release.",
          "type": "string"
        },
        {
          "const": "destructive",
          "description": "Removes something a person would have to reconstruct.",
          "type": "string"
        }
      ]
    },
    "CommandExecution": {
      "description": "How a command is actually run: the program and the words before the caller's own.\n\nThis is what forbids a cycle. A projection renders an invocation from the execution\ndescriptor, so a generated bridge always spells the *canonical* program — never the\nsurface it is a bridge for.",
      "properties": {
        "argv": {
          "description": "The words that precede the caller's arguments, the program's own name excluded.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "origin": {
          "$ref": "#/$defs/CommandOrigin",
          "description": "Which program."
        }
      },
      "required": [
        "origin",
        "argv"
      ],
      "type": "object"
    },
    "CommandId": {
      "description": "The canonical identity of one command.\n\nConstructed from the origin and the command path, never written by hand, so that a\nprojection cannot invent one and a rename of a display string cannot change one.",
      "type": "string"
    },
    "CommandInteractivity": {
      "description": "How a command behaves towards the caller's terminal and the caller's patience.",
      "oneOf": [
        {
          "const": "non_interactive",
          "description": "Runs, answers, exits. Safe to call from a machine surface.",
          "type": "string"
        },
        {
          "const": "interactive",
          "description": "Asks the person something, or reads the body of a record from a terminal. A\nmachine surface that offered it would hang.",
          "type": "string"
        },
        {
          "const": "long_running",
          "description": "Serves until it is stopped. A request/response surface cannot carry it.",
          "type": "string"
        }
      ]
    },
    "CommandOrigin": {
      "description": "Which program runs a command. Part of the identity, because the three are different\nprograms that share one name on the path.",
      "oneOf": [
        {
          "const": "executable",
          "description": "The Rust executable, `apps/majordomus-cli`: the read-only interfaces, generation,\nintrospection, the servers. Declared by clap.",
          "type": "string"
        },
        {
          "const": "tool",
          "description": "The shell tool, `bin/majordomus`: the task lifecycle. Declared by the shipped\ncommand registry and dispatched by the tool itself.",
          "type": "string"
        },
        {
          "const": "workflow",
          "description": "A workflow the repository declares for a person to run — a `just` recipe that is\nnot a generated bridge. Declared by the justfile and read from the runner's dump.",
          "type": "string"
        }
      ]
    },
    "CommandProjections": {
      "description": "Where one command appears, derived from its effect, its interactivity and its origin.\n\nEvery field is computed by [`super::policy`]. Nothing declares a projection, and no\nsurface keeps a list of what it carries: a surface asks the graph.",
      "properties": {
        "cli": {
          "description": "The command line, as typed.",
          "type": [
            "string",
            "null"
          ]
        },
        "cockpit": {
          "description": "The Cockpit address, when the surface carries it.",
          "type": [
            "string",
            "null"
          ]
        },
        "docs": {
          "description": "The page on the site. Every command has one.",
          "type": "string"
        },
        "http": {
          "description": "The HTTP route, when the capability behind it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "mcp": {
          "description": "The MCP tool name, when the capability behind it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "withheld": {
          "description": "Why a machine surface does not carry it, when one does not.",
          "type": [
            "string",
            "null"
          ]
        },
        "workflow": {
          "description": "The generated workflow bridge's recipe name.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "docs"
      ],
      "type": "object"
    },
    "CommandProvenance": {
      "description": "Where a node came from, in enough detail to open the file.",
      "properties": {
        "capability": {
          "anyOf": [
            {
              "$ref": "#/$defs/CapabilityId"
            },
            {
              "type": "null"
            }
          ],
          "description": "The capability this command runs, when it runs one."
        },
        "declared_in": {
          "description": "The repository-relative file that declares it.",
          "type": "string"
        },
        "read_by": {
          "description": "The command that reads that declaration, when a reader wants to reproduce it.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "declared_in"
      ],
      "type": "object"
    },
    "CommandRequirement": {
      "description": "One thing a command needs before it can run.",
      "oneOf": [
        {
          "const": "repository",
          "description": "A git repository.",
          "type": "string"
        },
        {
          "const": "layer",
          "description": "The `.ai/` layer, initialised.",
          "type": "string"
        },
        {
          "const": "task",
          "description": "An active task record.",
          "type": "string"
        },
        {
          "const": "executable",
          "description": "The Rust executable, built.",
          "type": "string"
        },
        {
          "const": "workflow_runner",
          "description": "The workflow runner, installed.",
          "type": "string"
        },
        {
          "const": "rust_toolchain",
          "description": "A cargo workspace and a toolchain to build it.",
          "type": "string"
        },
        {
          "const": "site",
          "description": "The site sources and its generator.",
          "type": "string"
        }
      ]
    },
    "CommandSecrecy": {
      "description": "How openly a value may be handled.",
      "oneOf": [
        {
          "const": "public",
          "description": "Ordinary: may be logged, completed, shown.",
          "type": "string"
        },
        {
          "const": "sensitive",
          "description": "A path or an identifier that names something private. Shown, never logged.",
          "type": "string"
        },
        {
          "const": "secret",
          "description": "A credential. Never completed, never logged, never cached.",
          "type": "string"
        }
      ]
    },
    "CommandValueChoice": {
      "description": "One value an argument accepts, from the declaration.",
      "properties": {
        "description": {
          "description": "Its help, when the declaration carries one.",
          "type": [
            "string",
            "null"
          ]
        },
        "value": {
          "description": "The value as typed.",
          "type": "string"
        }
      },
      "required": [
        "value"
      ],
      "type": "object"
    },
    "CommandValueSource": {
      "description": "Where a value for an argument comes from, when something in this repository knows the\nset.\n\nThis is the completion contract, and it is a property of the *argument*, not of a shell\nscript: the same source answers a shell's TAB, a generated form's select and a machine\nsurface's enumeration of what it will accept. Inference from the declaration comes\nfirst — a value-enum argument carries its own values, a `PATH` placeholder is a path —\nand only what cannot be inferred is annotated beside the command.",
      "oneOf": [
        {
          "description": "Nothing here knows the set; the caller types a value.",
          "properties": {
            "kind": {
              "const": "free",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "The declaration carries the values; they are on the argument.",
          "properties": {
            "kind": {
              "const": "enumerated",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A path in the filesystem.",
          "properties": {
            "kind": {
              "const": "path",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A path inside the repository.",
          "properties": {
            "kind": {
              "const": "repository_path",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A capability id, from the registry.",
          "properties": {
            "kind": {
              "const": "capability",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A command id, from this graph.",
          "properties": {
            "kind": {
              "const": "command",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A rule id, from the effective rule set.",
          "properties": {
            "kind": {
              "const": "rule",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "An object kind, from the index.",
          "properties": {
            "kind": {
              "const": "object_kind",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A git branch in this repository.",
          "properties": {
            "kind": {
              "const": "branch",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A graph id, from the graph registry.",
          "properties": {
            "kind": {
              "const": "graph",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A moment id, from the why catalogue.",
          "properties": {
            "kind": {
              "const": "moment",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A shell name, from the shells the activation supports.",
          "properties": {
            "kind": {
              "const": "shell",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        },
        {
          "description": "A secret. Never enumerated, never cached, never suggested.",
          "properties": {
            "kind": {
              "const": "secret",
              "type": "string"
            }
          },
          "required": [
            "kind"
          ],
          "type": "object"
        }
      ]
    },
    "Stability": {
      "description": "Where a capability stands, in the repository's own vocabulary for claims. A capability\nthat is `Planned` or `Unsupported` may be listed but is never executable through any\nprojection; the registry refuses to build otherwise.",
      "oneOf": [
        {
          "const": "implemented",
          "description": "Implemented, and no behavioural test names it yet.",
          "type": "string"
        },
        {
          "const": "behaviorally_verified",
          "description": "Implemented and proved by a behavioural test.",
          "type": "string"
        },
        {
          "const": "experimental",
          "description": "Implemented, executable, and expected to change.",
          "type": "string"
        },
        {
          "const": "planned",
          "description": "Specified and not implemented: listed, never executable.",
          "type": "string"
        },
        {
          "const": "unsupported",
          "description": "Considered and refused: listed with the reason, never executable.",
          "type": "string"
        }
      ]
    }
  },
  "description": "One command, from whichever program offers it.",
  "properties": {
    "aliases": {
      "description": "Other names that resolve to this node, declared once here and honoured by every\nprojection that has a use for one.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "arguments": {
      "description": "The arguments, in declaration order.",
      "items": {
        "$ref": "#/$defs/CommandArgument"
      },
      "type": "array"
    },
    "availability": {
      "$ref": "#/$defs/CommandAvailability",
      "description": "Where it means anything."
    },
    "deprecation": {
      "anyOf": [
        {
          "$ref": "#/$defs/CommandDeprecation"
        },
        {
          "type": "null"
        }
      ],
      "description": "Whether this is still the name to use."
    },
    "description": {
      "description": "The longer description, when the declaration carries one.",
      "type": [
        "string",
        "null"
      ]
    },
    "effect": {
      "$ref": "#/$defs/CommandEffect",
      "description": "What it changes."
    },
    "entrypoint": {
      "description": "Is this command an entry point of its group — the one a newcomer is offered?",
      "type": [
        "boolean",
        "null"
      ]
    },
    "execution": {
      "$ref": "#/$defs/CommandExecution",
      "description": "How it is run."
    },
    "group": {
      "description": "The group a person finds it under, when the declaration has groups.",
      "type": [
        "string",
        "null"
      ]
    },
    "id": {
      "$ref": "#/$defs/CommandId",
      "description": "The canonical identity."
    },
    "interactivity": {
      "$ref": "#/$defs/CommandInteractivity",
      "description": "How it behaves towards a terminal."
    },
    "invocation": {
      "description": "The command line a person types, rendered once here.",
      "type": "string"
    },
    "origin": {
      "$ref": "#/$defs/CommandOrigin",
      "description": "Which program runs it."
    },
    "path": {
      "description": "The words after the program's own name.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "projections": {
      "$ref": "#/$defs/CommandProjections",
      "description": "Where it appears."
    },
    "provenance": {
      "$ref": "#/$defs/CommandProvenance",
      "description": "Where it came from."
    },
    "runnable": {
      "description": "Can it be run on its own, or does it only group the commands under it?",
      "type": "boolean"
    },
    "stability": {
      "$ref": "#/$defs/Stability",
      "description": "Where it stands."
    },
    "summary": {
      "description": "One line.",
      "type": "string"
    },
    "tags": {
      "description": "Free tags.",
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "id",
    "origin",
    "path",
    "invocation",
    "summary",
    "runnable",
    "arguments",
    "execution",
    "effect",
    "interactivity",
    "stability",
    "availability",
    "provenance",
    "projections"
  ],
  "title": "CommandNode",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	1	worktree-status
mcp	covered	1	worktree-status
http	covered	1	worktree-status