HTTP API: commands

Every command this repository offers, from whichever program offers it: the Rust executable, the shell tool that carries the task lifecycle, and the workflows the repository declares for a person to run. Composed from the three declarations that already exist — the clap tree, the shipped command registry and the workflow runner's own dump — never from a list. Each command carries what running it changes, what it needs, where its argument values come from, and every surface that carries it, with the reason when one does not.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

commands

GET /api/v1/command commands.get

One command in full

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
benchmark required
cache disabled
MCP tool majordomus_command

Query parameters

name	type	required	description	examples
id	string	yes	The identity, `executable.worktree.status`.	worktree-status: "executable.worktree.status"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/command?id=executable.worktree.status"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	CommandNode	One command in full: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/commands commands.list

Every command, one line each

The commands this repository offers, filtered by the program that runs them, by what running them changes, or by text. A summary rather than the whole graph: enough to choose a command, and never so much that a client has to read every argument of every command to find one.

query
implemented
benchmark required
cache disabled
MCP tool majordomus_commands
MCP resource {"name": "commands", "uri": "majordomus://commands"}

Query parameters

name	type	required	description	examples
origin	string	no	Only the commands of one program: `executable`, `tool` or `workflow`.	one-program: "executable"
effect	string	no	Only the commands whose effect is at most this one: `read_only`, `local_mutation`, `repository_mutation`, `network_mutation`, `destructive`.	read-only: "read_only"
search	string	no	Only the commands matching this text in their invocation, summary, tags or identity.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/commands?origin=executable&effect=read_only"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	CommandIndex	Every command, one line each: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/commands/graph commands.graph

The whole command graph

The graph as one document, with its fingerprint and every diagnostic its build found: a duplicate identity, a recipe name two commands would take, an annotation that names a command which no longer exists. Deterministic — two builds over one tree produce the same document — so a client may cache against the fingerprint.

query
implemented
benchmark required
cache disabled
MCP tool majordomus_command_graph

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/commands/graph"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	CommandGraphReport	The whole command graph: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

CommandArgument

object

One argument of a command, as the declaration gives it plus what can be inferred.

property	type	required	description
name	string	yes	The argument's id.
long	string \| null	no	`--long`, without the dashes.
short	string \| null	no	`-s`, without the dash.
positional	boolean	yes	Given by position rather than by flag.
takes_value	boolean	yes	Takes a value at all; a flag does not.
required	boolean	yes	Must be given.
variadic	boolean	yes	Takes any number of values.
global	boolean	yes	Accepted by every command under the one that declares it.
help	string	yes	The help text, one line.
value_name	string \| null	no	The placeholder, `PATH`.
values	array of CommandValueChoice → CommandValueChoice	no	The values the declaration carries, each with its help.
defaults	array of string	no	The defaults, as the declaration renders them.
source	CommandValueSource → CommandValueSource	yes	Where further values come from.
secrecy	CommandSecrecy → CommandSecrecy	yes	How openly the value may be handled.

Used by CommandNode

CommandAvailability

object

Where a command means anything, and why not when it does not.

Derived from the repository environment rather than declared per command, so that a projection reads a field instead of re-deciding. The reason is carried because the answer a person needs is never false.

property	type	required	description
available	boolean	yes	Can it be run here, now?
reason	string \| null	no	Why not, in one line, when it cannot.
requires	array of CommandRequirement → CommandRequirement	no	What it needs, whether or not that is satisfied here.

Used by CommandNode

CommandDeprecation

object

A command that is no longer the name to use.

property	type	required	description
reason	string	yes	Why, in one line.
replaced_by	CommandId \| null → CommandId	no	What to use instead.

Used by CommandNode

CommandDiagnostic

object

One thing the build found.

property	type	required	description
severity	CommandDiagnosticSeverity → CommandDiagnosticSeverity	yes	How bad.
code	string	yes	A stable code, for a gate to match on.
message	string	yes	What is wrong, in one line.
commands	array of CommandId → CommandId	no	The nodes it is about.
remedy	string \| null	no	What to do about it.

Used by CommandGraph

CommandDiagnosticSeverity

"error" | "warning" | "info"

How bad a finding is.

errorThe graph is wrong and a projection built from it would be wrong.
warningWorth saying; the graph stands.
infoA fact a reader may want.

Used by CommandDiagnostic

CommandEffect

"read_only" | "local_mutation" | "repository_mutation" | "network_mutation" | "destructive"

What running a command changes. The one thing a surface policy is allowed to ask.

The order is the order of increasing consequence, and it is the order the derived exposure policy reads: a surface declares the strongest effect it will carry, and every node at or below it is projected there. Nothing configures a surface per command.

read_onlyReads and answers. Changes nothing anywhere.
local_mutationWrites only where the repository keeps a checkout's own state — the process's memory, .ai/local/, a build directory. Nothing a commit would carry.
repository_mutationWrites tracked files: generated artifacts, the worktree, git itself.
network_mutationReaches the network with an effect on the far side: a push, a deploy, a release.
destructiveRemoves something a person would have to reconstruct.

Used by CommandNode

CommandExecution

object

How a command is actually run: the program and the words before the caller's own.

This is what forbids a cycle. A projection renders an invocation from the execution descriptor, so a generated bridge always spells the canonical program — never the surface it is a bridge for.

property	type	required	description
origin	CommandOrigin → CommandOrigin	yes	Which program.
argv	array of string	yes	The words that precede the caller's arguments, the program's own name excluded.

Used by CommandNode

CommandGraph

object

The whole graph.

property	type	required	description
schema	string	yes	The schema of this document.
fingerprint	string	yes	A hash of the semantic content: the identity a cache and a generated projection key on. Nothing that varies between two runs over the same tree is in it.
commands	array of CommandNode → CommandNode	yes	Every command, in a deterministic order: origin, then path.
diagnostics	array of CommandDiagnostic → CommandDiagnostic	yes	What the build found.

Used by CommandGraphReport

CommandGraphReport

object

The whole graph, with what its build found.

property	type	required	description
graph	CommandGraph → CommandGraph	yes	The graph.
errors	integer (uint)	yes	How many findings are errors; a projection refuses to write while this is not zero.

Used by commands.graph

CommandId

string

The canonical identity of one command.

Constructed from the origin and the command path, never written by hand, so that a projection cannot invent one and a rename of a display string cannot change one.

Used by CommandDeprecation CommandDiagnostic CommandNode

CommandIndex

object

The commands this repository offers, filtered.

property	type	required	description
schema	string	yes	The schema of the graph these came from.
fingerprint	string	yes	The fingerprint of that graph: a client may cache against it.
total	integer (uint)	yes	How many commands the graph holds, before the filter.
commands	array of CommandSummary → CommandSummary	yes	The commands that matched, in graph order.

Used by commands.list

CommandInteractivity

"non_interactive" | "interactive" | "long_running"

How a command behaves towards the caller's terminal and the caller's patience.

non_interactiveRuns, answers, exits. Safe to call from a machine surface.
interactiveAsks the person something, or reads the body of a record from a terminal. A machine surface that offered it would hang.
long_runningServes until it is stopped. A request/response surface cannot carry it.

Used by CommandNode

CommandNode

object

One command, from whichever program offers it.

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

Used by commands.get CommandGraph

CommandOrigin

"executable" | "tool" | "workflow"

Which program runs a command. Part of the identity, because the three are different programs that share one name on the path.

executableThe Rust executable, apps/majordomus-cli: the read-only interfaces, generation, introspection, the servers. Declared by clap.
toolThe shell tool, bin/majordomus: the task lifecycle. Declared by the shipped command registry and dispatched by the tool itself.
workflowA workflow the repository declares for a person to run — a just recipe that is not a generated bridge. Declared by the justfile and read from the runner's dump.

Used by CommandExecution CommandNode

CommandProjections

object

Where one command appears, derived from its effect, its interactivity and its origin.

Every field is computed by super::policy. Nothing declares a projection, and no surface keeps a list of what it carries: a surface asks the graph.

property	type	required	description
cli	string \| null	no	The command line, as typed.
workflow	string \| null	no	The generated workflow bridge's recipe name.
mcp	string \| null	no	The MCP tool name, when the capability behind it declares one.
http	string \| null	no	The HTTP route, when the capability behind it declares one.
cockpit	string \| null	no	The Cockpit address, when the surface carries it.
docs	string	yes	The page on the site. Every command has one.
withheld	string \| null	no	Why a machine surface does not carry it, when one does not.

Used by CommandNode CommandSummary

CommandProvenance

object

Where a node came from, in enough detail to open the file.

property	type	required	description
declared_in	string	yes	The repository-relative file that declares it.
read_by	string \| null	no	The command that reads that declaration, when a reader wants to reproduce it.
capability	CapabilityId \| null → CapabilityId	no	The capability this command runs, when it runs one.

Used by CommandNode

CommandRequirement

One thing a command needs before it can run.

repositoryA git repository.
layerThe .ai/ layer, initialised.
taskAn active task record.
executableThe Rust executable, built.
workflow_runnerThe workflow runner, installed.
rust_toolchainA cargo workspace and a toolchain to build it.
siteThe site sources and its generator.

Used by CommandAvailability

CommandSecrecy

"public" | "sensitive" | "secret"

How openly a value may be handled.

publicOrdinary: may be logged, completed, shown.
sensitiveA path or an identifier that names something private. Shown, never logged.
secretA credential. Never completed, never logged, never cached.

Used by CommandArgument

CommandSummary

object

One command, as an index shows it: enough to choose, never enough to have to skim.

property	type	required	description
id	string	yes	The canonical identity.
invocation	string	yes	The command line a person types.
summary	string	yes	One line.
origin	string	yes	Which program runs it.
effect	string	yes	What running it changes.
group	string \| null	no	The group it is found under.
projections	CommandProjections → CommandProjections	yes	Where it appears.

Used by CommandIndex

CommandValueChoice

object

One value an argument accepts, from the declaration.

property	type	required	description
value	string	yes	The value as typed.
description	string \| null	no	Its help, when the declaration carries one.

Used by CommandArgument

CommandValueSource

one of 13 variants

Where a value for an argument comes from, when something in this repository knows the set.

This is the completion contract, and it is a property of the argument, not of a shell script: the same source answers a shell's TAB, a generated form's select and a machine surface's enumeration of what it will accept. Inference from the declaration comes first — a value-enum argument carries its own values, a PATH placeholder is a path — and only what cannot be inferred is annotated beside the command.

variant Nothing here knows the set; the caller types a value.

kind

"free"

yes

variant The declaration carries the values; they are on the argument.

kind

"enumerated"

yes

variant A path in the filesystem.

kind

"path"

yes

variant A path inside the repository.

kind

"repository_path"

yes

variant A capability id, from the registry.

kind

"capability"

yes

variant A command id, from this graph.

kind

"command"

yes

variant A rule id, from the effective rule set.

kind

"rule"

yes

variant An object kind, from the index.

kind

"object_kind"

yes

variant A git branch in this repository.

kind

"branch"

yes

variant A graph id, from the graph registry.

kind

"graph"

yes

variant A moment id, from the why catalogue.

kind

"moment"

yes

variant A shell name, from the shells the activation supports.

kind

"shell"

yes

variant A secret. Never enumerated, never cached, never suggested.

kind

"secret"

yes

Used by CommandArgument