Command line

majordomus

Majordomus control plane: a data-driven MCP server over the repository's .ai/ layer

The Rust executable of Majordomus. It reads the repository's provider-neutral AI layer under .ai/ and serves it, read-only, to MCP clients over stdio. The task lifecycle (init, start, check, finish, doctor, ...) is the shell tool bin/majordomus in the same repository; this executable does not implement those commands.

majordomus <COMMAND>

/docs/cli/ — this command on its own page

Subcommands: mcp, serve, capabilities, generate, bench, scope, web, why, distribution, env, commands, completion, worktree, product, release, quality, run, executions.

Arguments: none.

majordomus mcp

Serve the repository's AI layer to an MCP client over stdio (read-only)

majordomus mcp [OPTIONS]

/docs/cli/mcp/ — this command on its own page

Examples

• See what would be served, without serving it

  Builds the registry and the index of the repository in the working directory and prints the repository, the capabilities, the objects and every diagnostic, then exits. Nothing is served and nothing is written.

  $ majordomus mcp --inspect

  Verified by the example tests: exits 0; prints repository, capabilities.

• The same, as one JSON document for a script

  The shape `--inspect` prints for a person, as JSON: the repository, its discovery mode, the capabilities and the diagnostics, deterministic and safe to diff.

  $ majordomus mcp --inspect --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /repository/repository/root, /tools.

• Serve one MCP client on stdio

  The form an MCP client spawns: JSON-RPC frames in on stdin, frames out on stdout, logs on stderr, and the session ends at end of input. `--standalone` keeps this process to itself: no shared server, no HTTP, nothing written anywhere.

  $ majordomus mcp --standalone

  Verified by the example tests: answers initialize and tools/list on stdio, and exits 0 at end of input.

majordomus serve

Serve the same capabilities over HTTP on the loopback interface, with the home page, /openapi.json, /swagger and the documentation under /docs/ (read-only)

majordomus serve [OPTIONS]

/docs/cli/serve/ — this command on its own page

Examples

• Serve the same capabilities over HTTP on a free port

  Port 0 asks the operating system for a free port; the address is logged on stderr. `/` is the home page, generated from the surfaces this process resolved; the document at /openapi.json is the same one `majordomus generate` commits; /swagger is the Swagger UI over it; /docs/ is this repository's documentation when it has been built for that mount.

  $ majordomus serve --port 0

  Verified by the example tests: binds a port, answers GET /openapi.json, exits 0 when stopped.

majordomus capabilities

Introspect the capability registry: what exists, where it came from, how it is exposed

majordomus capabilities [OPTIONS] <COMMAND>

/docs/cli/capabilities/ — this command on its own page

Subcommands: list, describe, schema, projections, validate.

majordomus capabilities list

Every capability, one line each, with its projections

majordomus capabilities list [OPTIONS]

/docs/cli/capabilities/list/ — this command on its own page

Examples

• Which capabilities the command line itself dispatches to

  One line per capability exposed through the `cli` projection, with the projections of each. The registry answers this; no list of capabilities is written in the command line's own declaration.

  $ majordomus capabilities list --exposure cli

  Verified by the example tests: exits 0; prints capabilities.list, capabilities.describe.

• Every capability as one JSON document

  The whole registry for a script: each capability with its kind, its provenance and every projection it has.

  $ majordomus capabilities list --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /capabilities.

majordomus capabilities describe

One capability by canonical id: schemas, provenance, every projection

majordomus capabilities describe [OPTIONS] <ID>

/docs/cli/capabilities/describe/ — this command on its own page

Examples

• One capability in full, by its canonical id

  Its kind, its input and output schemas, where it was composed, and every projection of it: the MCP tool or resource, the HTTP route, the CLI path.

  $ majordomus capabilities describe objects.get

  Verified by the example tests: exits 0; prints objects.get, GET /api/v1/object.

majordomus capabilities schema

The canonical input or output JSON Schema of one capability

majordomus capabilities schema [OPTIONS] <ID>

/docs/cli/capabilities/schema/ — this command on its own page

Examples

• The canonical output schema of a capability

  The JSON Schema the MCP and OpenAPI projections are derived from; `--side input` prints the schema of what the capability accepts.

  $ majordomus capabilities schema objects.get --side output

  Verified by the example tests: exits 0; prints one JSON document carrying /title.

majordomus capabilities projections

Where each capability is projected, and every claim its surface does not answer

majordomus capabilities projections [OPTIONS]

/docs/cli/capabilities/projections/ — this command on its own page

Examples

• Every exposure a capability claims that its surface does not answer

  `rows: 0` is the closure `project.interfaces-are-projections` asks for: every declared command line, route and tool is answered by the surface that carries it. The commands no capability claims are reported beside it, as the measure of how much of the command line is still hand-written.

  $ majordomus capabilities projections --unmet

  Verified by the example tests: exits 0.

• Where one module's capabilities appear

  A row per capability with the command line, HTTP route and MCP tool it reaches, so a capability that exists but is reachable from nowhere is visible as one.

  $ majordomus capabilities projections --module worktree

  Verified by the example tests: exits 0; prints worktree.topology, majordomus worktree topology.

majordomus capabilities validate

Build the registry and every projection; exit 10 with every violation named

majordomus capabilities validate [OPTIONS]

/docs/cli/capabilities/validate/ — this command on its own page

Examples

• Prove the registry and every projection of it

  Builds the registry, the MCP and HTTP surfaces, the OpenAPI document, the command line's documentation and the benchmark coverage, and names every failure. Exit 10 when anything is unmet.

  $ majordomus capabilities validate

  Verified by the example tests: exits 0; prints validate: 0 failure(s), OK cli.

majordomus generate

Write the committed projections of the registry (docs/generated), or check that they are current

majordomus generate [OPTIONS] [TARGET]

/docs/cli/generate/ — this command on its own page

Examples

• Write every committed projection

  The OpenAPI document, the capability reference, the command-line reference and its JSON, the registry manifest, the benchmark matrix, the shell tool's allow-lists, the provider bootstraps and the site's registry dataset — all from the one registry and the one clap declaration.

  $ majordomus generate

  Verified by the example tests: exits 0.

• Refuse a tree whose projections are stale

  Writes nothing and compares instead: exit 0 when every committed projection is what the sources produce, exit 10 with each stale file named. This is the form CI runs.

  $ majordomus generate
  $ majordomus generate --check

  Verified by the example tests: exits 0.

• One target only

  Each target can be written on its own while a change is iterated on; `majordomus generate` with no target writes all of them.

  $ majordomus generate openapi

  Verified by the example tests: exits 0.

majordomus bench

Time every externally callable operation (each capability directly, over MCP and over HTTP, and the transports' own operations), report coverage, compare with the accepted baseline

majordomus bench [OPTIONS] [COMMAND] [ID]

/docs/cli/bench/ — this command on its own page

Subcommands: coverage, baseline.

Examples

• Time the capabilities in process

  The quick profile takes few samples, and `--transport direct` measures the executor without spawning a server. Nothing is written under .ai/local/ with `--no-write`.

  $ majordomus bench --transport direct --profile quick --no-write --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /results, /profile.

majordomus bench coverage

Every required target and whether it is covered; the denominator is generated from the registry

majordomus bench coverage [OPTIONS]

/docs/cli/bench/coverage/ — this command on its own page

Examples

• Every required benchmark target and whether it is covered

  The denominator is generated from the registry: every executable capability, on every transport it is exposed on, plus the transports' own operations.

  $ majordomus bench coverage --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /lines, /tallies.

• Fail when a target is missing

  Exit 10 when any required target is uncovered or waived, so a capability that nothing times cannot be merged.

  $ majordomus bench coverage --check

  Verified by the example tests: exits 0.

majordomus bench baseline

The accepted baseline of this platform under .ai/repo/benchmarks/rust/

majordomus bench baseline [OPTIONS] <COMMAND>

/docs/cli/bench/baseline/ — this command on its own page

Subcommands: update.

majordomus bench baseline update

Run the benchmarks and record them as this platform's baseline (a reviewable, tracked file)

majordomus bench baseline update [OPTIONS]

/docs/cli/bench/baseline/update/ — this command on its own page

Examples

• Record this platform's accepted baseline

  Runs the benchmarks and writes the result under .ai/repo/benchmarks/rust/ as a tracked, reviewable file. The full profile is the default; the quick profile is for trying the path out. A dirty work tree is refused unless --allow-dirty says otherwise.

  $ majordomus bench baseline update --profile quick --allow-dirty

  Verified by the example tests: exits 0.

majordomus scope

The repository scope: what a worker reads and what it never reads; with paths, whether each is in or out and why

majordomus scope [OPTIONS] [PATHS]

/docs/cli/scope/ — this command on its own page

Examples

• What a worker reads of this repository

  With no path, the declaration itself and the tally: how many tracked files are in the scope and how many are out.

  $ majordomus scope

  Verified by the example tests: exits 0.

• Judge paths, and say which rule decided

  For each path: in or out, and the rule that decided it. `--check` exits 10 when any path given is out, which is how a hook refuses to read one.

  $ majordomus scope docs/CLI.md --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /0/verdict, /0/rule.

majordomus web

The repository's web surfaces: what is exposed, where it is mounted, what produced it, and whether the topology is valid

majordomus web [OPTIONS] [COMMAND]

/docs/cli/web/ — this command on its own page

Subcommands: list, explain, validate, manifest, report, compose.

Examples

• The topology, from the command with no subcommand

  `web` with nothing after it lists, because listing is what a person wants when they ask what this repository exposes.

  $ majordomus web

  Verified by the example tests: exits 0; prints ID, MOUNT.

majordomus web list

Every discovered surface: id, kind, mount, producer

majordomus web list [OPTIONS]

/docs/cli/web/list/ — this command on its own page

Examples

• Every web surface this repository exposes

  The resolved topology, in route-precedence order: the routes the executable answers itself, the application's site, and every generated report that declared itself under the generated web root. Nothing is registered anywhere; each line was discovered.

  $ majordomus web list

  Verified by the example tests: exits 0; prints MOUNT, /api/v1, /swagger.

majordomus web explain

Why each surface exists and where each of its values came from

majordomus web explain [OPTIONS] [ID]

/docs/cli/web/explain/ — this command on its own page

Examples

• Why a surface exists and where each of its values came from

  For each field a reader could be surprised by — the mount, the kind, the directory — the source that decided it: a producer's own declaration, the site configuration, the capability registry, or the model's documented default.

  $ majordomus web explain swagger

  Verified by the example tests: exits 0; prints swagger, came from.

majordomus web validate

Check the topology's invariants; exit 10 on any error finding

majordomus web validate [OPTIONS]

/docs/cli/web/validate/ — this command on its own page

Examples

• Check the topology before anything serves or publishes it

  Two surfaces claiming one path, a surface nested inside another's subtree, a directory outside the generated root or one that walks out of the repository: each is a named finding with the surface, the value, its source and the fix. Exit 10 on any error finding. `--artifacts` also requires every static surface's directory and index to exist, which is what serving and publishing need.

  $ majordomus web validate

  Verified by the example tests: exits 0; prints no conflict.

majordomus web manifest

Write the resolved topology to the generated manifest

majordomus web manifest [OPTIONS]

/docs/cli/web/manifest/ — this command on its own page

Examples

• Write the resolved topology down for another tool to read

  The manifest under the generated web root is derived state: a publisher or a CI job may read it instead of resolving the topology again, and nothing may edit it, because the next run overwrites it from the same discovery.

  $ majordomus web manifest

  Verified by the example tests: exits 0; prints web manifest, surface.

majordomus web report

Render a generated report into its own surface under the generated web root

majordomus web report [OPTIONS] <COMMAND>

/docs/cli/web/report/ — this command on its own page

Subcommands: tests, benchmarks, ui.

majordomus web report tests

The test run: the behavioural cases' report, and the crate's own totals

majordomus web report tests [OPTIONS]

/docs/cli/web/report/tests/ — this command on its own page

Examples

• Render the suite's own results into the /tests surface

  The runner writes its report with `MJ_TEST_REPORT=<file> bash test/run.sh`; this renders it, keeps the machine-readable results beside the page, and declares the directory so discovery finds it. Without that file there is nothing to render and the command says so rather than publishing an empty page.

  $ majordomus web report tests --suite target/web/run.tsv

  Verified by the example tests: exits 13.

majordomus web report benchmarks

The benchmark run: a results document, or the accepted baseline

majordomus web report benchmarks [OPTIONS]

/docs/cli/web/report/benchmarks/ — this command on its own page

Examples

• Render a benchmark run into the /benchmarks surface

  Reads a results document — a run's own output, or an accepted baseline under the layer's benchmarks section, which have the same shape — and renders every measured target ordered by median. It measures nothing itself: a figure on the page is a figure a run produced.

  $ majordomus web report benchmarks --from .ai/repo/benchmarks/rust/baseline.macos-aarch64-debug.json

  Verified by the example tests: exits 13.

majordomus web report ui

The UI conformance audit, rendered as a section of the test surface (/tests/ui)

majordomus web report ui [OPTIONS]

/docs/cli/web/report/ui/ — this command on its own page

Examples

• Render the UI conformance audit into /tests/ui

  `scripts/ui audit` drives a browser over every page of the built site at every width the compiled stylesheet's breakpoints imply, and writes one results document; this renders it. The rendering is a section of the test surface rather than a surface of its own, because a conformance run is a test run and the topology refuses a surface mounted inside another's subtree. Without that document there is nothing to render and the command says so.

  $ majordomus web report ui --from target/web/run-ui.json

  Verified by the example tests: exits 13.

majordomus web compose

Compose every published surface into one publishable tree

majordomus web compose [OPTIONS]

/docs/cli/web/compose/ — this command on its own page

Examples

• Compose every published surface into one publishable tree

  Each producer owns its own output directory; publication needs one tree, and the mapping is the resolved mount and nothing else. A surface that is discovered is published without a copy step being written anywhere, and a repository with nothing generated yet composes an empty tree rather than an error. Where a surface exists and its directory does not, composition refuses and names the producer to run.

  $ majordomus web compose --destination target/site

  Verified by the example tests: exits 0.

majordomus why

The operational moments this tool answers: the catalogue, one moment, the audiences and areas, a diagnosis of your own week, and the catalogue's own validation

majordomus why [OPTIONS] [COMMAND]

/docs/cli/why/ — this command on its own page

Subcommands: list, show, audiences, areas, diagnose, validate.

Examples

• The operational moments this repository holds

  `why` with nothing after it lists, because listing is what a person wants when they ask what this section is. The count on the last line is computed from the catalogue; no number anywhere is written down.

  $ majordomus why

  Verified by the example tests: exits 0; prints SLUG, moment(s).

majordomus why list

Every operational moment, narrowed by any facet the catalogue reports

majordomus why list [OPTIONS]

/docs/cli/why/list/ — this command on its own page

Examples

• Every public moment, in presentation order

  Drafts are excluded unless `--all` is given. The facets a listing may be narrowed by are the ones the catalogue itself reports, so an audience or an area added as a file is a filter without anything being registered.

  $ majordomus why list

  Verified by the example tests: exits 0; prints SLUG.

• Only what one audience recognises

  Membership is declared by each moment and never listed in the audience's own file, so this answer is derived. An audience the catalogue does not have is an invalid input naming the ones it does, not an empty answer.

  $ majordomus why list --audience fixture-team

  Verified by the example tests: exits 0; prints SLUG.

• The same, as the shape the API and MCP answer with

  One domain model behind every projection: this document is what `GET /api/v1/why` returns and what the `majordomus_why` tool answers, including the derived facets and the catalogue's fingerprint.

  $ majordomus why list --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /counts/moments, /facets/audiences, /fingerprint.

majordomus why show

One moment in full, with every relation derived from its metadata

majordomus why show [OPTIONS] <ID>

/docs/cli/why/show/ — this command on its own page

Examples

• One moment, with every relation derived from its metadata

  The record as its file declares it, then what nobody authored: the responsibilities its claims belong to, the moments that name it, and the moments nearest it by shared area, audience and tag.

  $ majordomus why show fixture-moment

  Verified by the example tests: exits 0; prints fixture-moment, derived.

majordomus why audiences

Every audience, with the moments that name it

majordomus why audiences [OPTIONS]

/docs/cli/why/audiences/ — this command on its own page

Examples

• Who recognises what, with the counts derived

  Each audience with how many public moments name it. The number is computed from the moments; an audience's own file never lists one.

  $ majordomus why audiences

  Verified by the example tests: exits 0; prints SLUG, TITLE.

majordomus why areas

Every operational area, with the moments that fall under it

majordomus why areas [OPTIONS]

/docs/cli/why/areas/ — this command on its own page

Examples

• The operational areas, with the counts derived

  The same relation read the other way: each area with the public moments that fall under it.

  $ majordomus why areas

  Verified by the example tests: exits 0; prints SLUG, TITLE.

majordomus why diagnose

What the symptoms you recognise imply: the areas they weigh towards and the mechanisms that answer them

majordomus why diagnose [OPTIONS]

/docs/cli/why/diagnose/ — this command on its own page

Examples

• The questionnaire, assembled from the catalogue's own signals

  With no selection there is nothing to diagnose, so the questions are printed instead of an empty answer. Every line is a signal a moment declares; nothing here is a list of questions.

  $ majordomus why diagnose

  Verified by the example tests: exits 0; prints Which of these happened to you this week?.

• What the symptoms you recognise imply

  A name is a signal id or a moment id. The answer is counting, not inference: each recommendation carries the moments that produced it, and there is no percentage because there is no model behind one.

  $ majordomus why diagnose --signal fixture-signal

  Verified by the example tests: exits 0; prints moment(s) matched, fixture-moment.

majordomus why validate

Every finding over the catalogue; exit 10 when any is an error

majordomus why validate [OPTIONS]

/docs/cli/why/validate/ — this command on its own page

Examples

• Check the catalogue before anything projects it

  A reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a public record that does not meet the floor its status promises. Exit 10 on any error.

  $ majordomus why validate

  Verified by the example tests: exits 0; prints moment(s), valid.

majordomus distribution

How this project is packaged, published and installed: the platforms, the artifact names, the installer, the releases

majordomus distribution [OPTIONS] [COMMAND]

/docs/cli/distribution/ — this command on its own page

Subcommands: show, status, validate, targets, matrix, artifact, releases, metadata, build.

Examples

• How this project is installed

  `distribution` with nothing after it shows the model: the one-line install command, where an installation goes, and how many platforms a release builds. Every value comes from share/distribution.yaml, which is the only place any of them is written.

  $ majordomus distribution

  Verified by the example tests: exits 0; prints binary, install, targets.

majordomus distribution show

The model: the install command, where an installation goes, and every declared target

majordomus distribution show [OPTIONS]

/docs/cli/distribution/show/ — this command on its own page

Examples

• The distribution model as one JSON document

  The same answer as a document a script can read: the install command, the default locations, and every declared target with the artifact name the naming function derives for it. This is what the website's install block and the cockpit's install card render.

  $ majordomus distribution show --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /install_command, /targets.

majordomus distribution status

Whether the advertised one-line installation works right now, and what is missing when it does not

majordomus distribution status [OPTIONS]

/docs/cli/distribution/status/ — this command on its own page

Examples

• Whether the published one-line installation works right now

  The operator's question — *can a machine that has never seen this project install it with the advertised command?* — answered from the distribution model and the release records, without touching the network. Each check names what was observed; a failing one names its cause and the command that changes it. Shown here in a repository that has published nothing, where the answer is no and the exit code is 10, which is what makes it usable as a check rather than as prose. `distribution validate` is the gate over the model itself; this is the gate over the state a user meets.

  $ majordomus distribution status

  Verified by the example tests: exits 10.

majordomus distribution validate

Every invariant of the model and of the release records; exit 10 with each violation named

majordomus distribution validate [OPTIONS]

/docs/cli/distribution/validate/ — this command on its own page

Examples

• Every invariant of the model and of the release records

  Refuses a duplicate target id or triple, two targets deriving one artifact name, a Linux target with no C library, a published target with nothing to build it on, an unbuilt target with no recorded reason, a base URL that is not HTTPS, and a release record that misses a supported target, renames an artifact or serves one from another host. Exits 10 with each violation named.

  $ majordomus distribution validate

  Verified by the example tests: exits 0; prints distribution.

majordomus distribution targets

Every declared target, one line each, with the artifact name it derives

majordomus distribution targets [OPTIONS]

/docs/cli/distribution/targets/ — this command on its own page

Examples

• Every platform, and whether a release builds it

  One line per declared target: its id, its Rust target triple, whether it is supported, experimental or unavailable, and how it is written in prose. The supported-platform table in the documentation and the installer's own refusal message are rendered from these same rows.

  $ majordomus distribution targets

  Verified by the example tests: exits 0; prints RUST TARGET, supported.

majordomus distribution matrix

The release build matrix, as the release workflow reads it

majordomus distribution matrix [OPTIONS]

/docs/cli/distribution/matrix/ — this command on its own page

Examples

• The release build matrix the workflow runs

  One entry per published target, with the runner it is built on, the packages that runner needs, and the artifact name with `{tag}` where a release's tag goes. The release workflow reads this and states no platform of its own; adding a target to the model adds a build here and nowhere else.

  $ majordomus distribution matrix

  Verified by the example tests: exits 0; prints one JSON document carrying /include, /binary.

majordomus distribution artifact

The archive name and root directory a target and a tag derive

majordomus distribution artifact [OPTIONS]

/docs/cli/distribution/artifact/ — this command on its own page

Examples

• What one target and one tag are called

  The one naming function, asked directly: the archive's name, the directory it unpacks into, and where a release publishes it. `scripts/release-package` asks this rather than composing a name, so a change to the naming function reaches the packaging without an edit.

  $ majordomus distribution artifact --target aarch64-apple-darwin --tag v0.2.0 --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /name, /root, /url.

majordomus distribution releases

Every recorded release, newest first, and the one an unpinned installation resolves to

majordomus distribution releases [OPTIONS]

/docs/cli/distribution/releases/ — this command on its own page

Examples

• What has been published, and what an unpinned install resolves to

  Every release record this repository holds, newest first, and which of them the stable pointer names: the highest version among the stable, unwithdrawn records. The pointer is derived on every read and is authored nowhere.

  $ majordomus distribution releases

  Verified by the example tests: exits 0.

majordomus distribution metadata

The public metadata one release record publishes, rendered from the record alone

majordomus distribution metadata [OPTIONS]

/docs/cli/distribution/metadata/ — this command on its own page

Examples

• What one release record publishes

  The public metadata a record turns into, rendered from the record and the model alone: the release pipeline prints this before it commits anything, and the installer's own tests serve it as a release that never existed. Shown here in a repository that has published nothing, where the record does not exist and the command says which file it wanted and exits 10 rather than inventing one.

  $ majordomus distribution metadata --record .ai/repo/releases/v0.2.0.yaml

  Verified by the example tests: exits 10.

majordomus distribution build

What this executable is: version, target triple, profile, commit

majordomus distribution build [OPTIONS]

/docs/cli/distribution/build/ — this command on its own page

Examples

• What this executable is

  The crate version, the Rust target triple, the profile and the commit, all compiled in at build time. An installed binary answers this without a repository, a toolchain or git, which is what makes a support question answerable.

  $ majordomus distribution build

  Verified by the example tests: exits 0; prints version, target, commit.

majordomus env

What this checkout is: the project, version control, the toolchains it declares, what the layer holds, the workflows, the provider projections and the local services

majordomus env [OPTIONS] [COMMAND]

/docs/cli/env/ — this command on its own page

Subcommands: status, banner, export, explain.

Examples

• What this checkout is

  `env` with nothing after it resolves the whole snapshot: the project and its version, the repository and its layer, version control, the toolchains the repository declares, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services. This is the resolution that counts the layer, so it builds the index and writes the cache the banner reads.

  $ majordomus env

  Verified by the example tests: exits 0; prints project, repository, resolution.

majordomus env status

The whole snapshot, resolved in full: what the layer holds is counted, and the cache the banner reads is written

majordomus env status [OPTIONS]

/docs/cli/env/status/ — this command on its own page

Examples

• The snapshot as one document

  The same value the HTTP route `/api/v1/environment` and the MCP resource `majordomus://environment` answer with, and the value the banner renders. Every field carries where it came from under `provenance`, and a value nothing could resolve is absent rather than zero.

  $ majordomus env status --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /schema, /project/version, /repository/name, /provenance.

majordomus env banner

Render the snapshot for a terminal. Goes to standard error, never standard output, because direnv reads standard output as the environment it is setting

majordomus env banner [OPTIONS]

/docs/cli/env/banner/ — this command on its own page

Examples

• The two-line form, at a width you choose

  What `direnv` renders on entering the repository. It resolves fast — it never builds the index — and it writes to standard error, because direnv reads the standard output of a `.envrc` as the environment it is applying. `--width` renders as if the terminal were that wide, which is what makes the layout testable.

  $ majordomus env banner --mode compact --width 80

  Verified by the example tests: exits 0.

majordomus env export

The variable assignments a shell in this repository benefits from, for `eval`. Assignments only: no command, no side effect

majordomus env export [OPTIONS]

/docs/cli/env/export/ — this command on its own page

Examples

• The assignments a shell in this repository wants

  Assignments and nothing else, safe to `eval`: no command runs, no file is touched, and every value is quoted so that a repository path holding a quote or a `$(...)` cannot become shell code. This is the whole of what `.envrc` needs from Majordomus.

  $ majordomus env export --shell direnv

  Verified by the example tests: exits 0; prints export MAJORDOMUS_ROOT=.

majordomus env explain

Where each value came from: the file, command or constant that decided it, the resolver that read it, and how far it can be trusted

majordomus env explain [OPTIONS] [FIELD]

/docs/cli/env/explain/ — this command on its own page

Examples

• Where one value came from

  An inferred system without provenance is magic. Every field of the snapshot can name the file, command or compile-time constant that decided it, the resolver that read it, and whether it was read now, taken from the cache, or not resolved at all.

  $ majordomus env explain project.version

  Verified by the example tests: exits 0; prints project.version, source, resolver.

majordomus commands

Every command this repository offers, from whichever program offers it: the graph, one command, where each one is projected, and the workflow bridge derived from it

majordomus commands [OPTIONS] [COMMAND]

/docs/cli/commands/ — this command on its own page

Subcommands: list, show, explain, graph, bridge.

Examples

• Every command this repository offers

  The command graph, composed from the three declarations that already exist: the clap tree of this executable, the shipped command registry of the shell tool, and the recipes the workflow runner describes. One line per command, with the program that runs it and what running it changes.

  $ majordomus commands

  Verified by the example tests: exits 0; prints commands, executable, read-only.

majordomus commands list

Every command, one line each: what it is, what running it changes, and where it is projected

majordomus commands list [OPTIONS]

/docs/cli/commands/list/ — this command on its own page

Examples

• Only what reads

  The filters are the graph's own vocabulary rather than a search over text: `--effect read-only` is every command that changes nothing anywhere, which is the same predicate the exposure policy uses to decide what a machine surface may call.

  $ majordomus commands list --effect read-only

  Verified by the example tests: exits 0; prints read-only.

majordomus commands show

One command in full: its arguments, its effect, what it needs, and every surface that carries it

majordomus commands show [OPTIONS] <ID>

/docs/cli/commands/show/ — this command on its own page

Examples

• One command, and every surface that carries it

  The arguments with the source of each one's values, the effect, and the projections: the command line, the workflow recipe, the MCP tool, the HTTP route, the Cockpit and the page. A surface that withholds it says why.

  $ majordomus commands show executable.worktree.status

  Verified by the example tests: exits 0; prints executable.worktree.status, projections.

majordomus commands explain

Why one command appears where it does: the declaration it came from, the policy that placed it, and the reason for every surface that withholds it

majordomus commands explain [OPTIONS] <ID>

/docs/cli/commands/explain/ — this command on its own page

Examples

• Why a command appears where it does

  The same command with its provenance: the file that declares it, the reader that found it, the capability behind it when there is one, what it requires, and the file the exposure policy lives in. Nothing about a command's placement is a mystery a grep has to solve.

  $ majordomus commands explain executable.serve

  Verified by the example tests: exits 0; prints declared in, policy.

majordomus commands graph

The whole graph as one document, with its fingerprint and every diagnostic

majordomus commands graph [OPTIONS]

/docs/cli/commands/graph/ — this command on its own page

Examples

• The whole graph as one document

  Deterministic and fingerprinted: two builds over one tree produce the same bytes, which is what lets the workflow bridge, the completion index and the Cockpit all key on the fingerprint instead of regenerating.

  $ majordomus commands graph --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /schema, /fingerprint, /commands.

majordomus commands bridge

Materialise the workflow bridge from the graph, and refresh the cache the completion reads; writes nothing when the graph has not changed

majordomus commands bridge [OPTIONS]

/docs/cli/commands/bridge/ — this command on its own page

Examples

• The workflow runner's recipes, derived

  Every command of both programs, written as a recipe that runs the canonical program with the caller's own arguments. It goes under .ai/local/cache/, which no commit carries, and it is rewritten only when the graph's fingerprint changes.

  $ majordomus commands bridge

  Verified by the example tests: exits 0; prints bridge, recipe.

majordomus completion

Completion for any surface, answered from the command graph: the candidates a shell asks for, and the one-time integration that asks

majordomus completion [OPTIONS] [COMMAND]

/docs/cli/completion/ — this command on its own page

Subcommands: query, init, install.

Examples

• The integration a person installs once

  With no subcommand, the shell integration for zsh. It contains no command, no flag and no identifier: every candidate comes from a query against the command graph of the repository the shell is in, so one integration serves every checkout and never goes stale.

  $ majordomus completion

  Verified by the example tests: exits 0; prints completion query, compdef.

majordomus completion query

The candidates for one command line, from the command graph. What a shell adapter calls on every TAB

majordomus completion query [OPTIONS] [WORD]

/docs/cli/completion/query/ — this command on its own page

Examples

• What a shell asks on every TAB

  The words of the command line and the position of the cursor; back come the candidates with their descriptions. The same call answers the workflow runner's completion with `--surface workflow`, resolving the recipe name to the command it bridges and then completing that command's own arguments.

  $ majordomus completion query --surface cli -- majordomus work

  Verified by the example tests: exits 0; prints worktree.

majordomus completion init

The shell integration to load once, which carries no command of its own and asks this executable for every candidate

majordomus completion init [OPTIONS]

/docs/cli/completion/init/ — this command on its own page

Examples

• The same, for bash

  A different shell's protocol, the same question. Both adapters read the words being completed, find the cursor, ask this executable and print what comes back.

  $ majordomus completion init --shell bash

  Verified by the example tests: exits 0; prints completion query, complete -F.

majordomus completion install

Put that integration into the shell's startup file, between managed markers, so that no one maintains it by hand

majordomus completion install [OPTIONS]

/docs/cli/completion/install/ — this command on its own page

Examples

• The one line a person adds to their shell, added for them

  Writes the integration into the shell's startup file between `# >>> MAJORDOMUS >>>` markers: nothing outside them is touched, running it twice changes nothing, and `--remove` takes it out again. It is never a side effect of anything else — installing into a person's home directory is its own decision, so it is its own command. `--dry-run` says what would change and writes nothing.

  $ majordomus completion install --shell zsh --dry-run

  Verified by the example tests: exits 0.

majordomus worktree

The branch-to-worktree topology: where every linked worktree belongs (`<repo>-wt/<branch>`), where each one is, and the lifecycle — create, migrate, repair, guard

majordomus worktree [OPTIONS] [COMMAND]

/docs/cli/worktree/ — this command on its own page

Subcommands: status, list, topology, root, path, inspect, create, ensure, migrate, validate, doctor, guard, repair, remove, cleanup, branches.

Examples

• Where am I, and is that where I belong?

  `worktree` with nothing after it answers the question a worker asks before starting: which branch this is, whether this directory is that branch's canonical worktree (or the primary checkout on the trunk), what is uncommitted here, and how many errors the whole topology carries. The same answer from the primary checkout and from four directories deep inside a linked worktree.

  $ majordomus worktree

  Verified by the example tests: exits 0; prints branch, worktree, container.

majordomus worktree status

Where this call is — branch, worktree, canonical or not, uncommitted work — and how many errors the whole topology carries; exit 10 when this worktree is out of place

majordomus worktree status [OPTIONS]

/docs/cli/worktree/status/ — this command on its own page

Examples

• The current worktree as one document

  The same answer as JSON: the repository, the container, the trunk and how it was decided, this worktree with its standing and diagnostics, and whether it is where it belongs. This is what the MCP tool `majordomus_worktree_status` and `GET /api/v1/worktrees/status` answer.

  $ majordomus worktree status --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /worktree/standing, /container/path, /trunk/source, /canonical.

majordomus worktree list

Every registered worktree with its standing, one line each; exit 10 when the topology has an error

majordomus worktree list [OPTIONS]

/docs/cli/worktree/list/ — this command on its own page

Examples

• Every worktree, the misplaced ones obvious

  The primary checkout first, then every linked worktree with its standing, its branch, where it belongs when it is somewhere else, and its uncommitted work. The primary checkout is exempt from the path rule and held to the trunk rule instead.

  $ majordomus worktree create feature/example
  $ majordomus worktree list

  Verified by the example tests: exits 0; prints PRIMARY, CANONICAL, -wt/feature/example.

majordomus worktree topology

The whole topology: repository, container, trunk, every worktree, every branch without a worktree, every diagnostic; exit 10 when it has an error

majordomus worktree topology [OPTIONS]

/docs/cli/worktree/topology/ — this command on its own page

Examples

• The whole topology as one document

  The repository, the container, the trunk, every worktree, every branch with or without a worktree, every diagnostic with its code and remedy, and the tallies. This is what the MCP resource `majordomus://worktrees`, the tool `majordomus_worktrees`, `GET /api/v1/worktrees` and the Cockpit all render.

  $ majordomus worktree topology --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /container/path, /trunk/branch, /worktrees/0/standing, /branches/0/name, /tallies/worktrees, /valid.

majordomus worktree root

Print the container every linked worktree belongs under, and nothing else: `cd "$(majordomus worktree root)"`

majordomus worktree root [OPTIONS]

/docs/cli/worktree/root/ — this command on its own page

Examples

• The container, for the shell

  Prints the container and nothing else, so a shell can use it: `cd "$(majordomus worktree root)"`. It is the primary checkout's sibling named with `-wt`, derived from git's own identity and never from the current directory — which is why running this inside a linked worktree does not answer a container inside that worktree.

  $ majordomus worktree root

  Verified by the example tests: exits 0; prints -wt.

majordomus worktree path

Print the canonical path of a branch, and nothing else: `cd "$(majordomus worktree path feature/x)"`. Derived from the name; the branch need not exist

majordomus worktree path [OPTIONS] <BRANCH>

/docs/cli/worktree/path/ — this command on its own page

Examples

• The canonical path of a branch, for the shell

  A child process cannot change its parent shell's directory, so nothing here pretends to: this prints one path and the shell does the rest — `cd "$(majordomus worktree path feature/x)"`. The path is the branch name under the container, hierarchy kept; the branch need not exist yet.

  $ majordomus worktree path feature/providers/streaming

  Verified by the example tests: exits 0; prints -wt/feature/providers/streaming.

majordomus worktree inspect

One branch: its canonical path, whether it exists, what occupies the path, the worktree holding it, and what stands in the way

majordomus worktree inspect [OPTIONS] <BRANCH>

/docs/cli/worktree/inspect/ — this command on its own page

Examples

• One branch, before creating its worktree

  Where the branch's worktree belongs, whether the branch exists, whether anything occupies the path, and what would stand in the way. For a branch that does not exist yet, the answer is the path `worktree create` would use and the command to run.

  $ majordomus worktree inspect feature/new-dashboard

  Verified by the example tests: exits 0; prints -wt/feature/new-dashboard, does not exist yet.

majordomus worktree create

Create the canonical worktree of a branch, creating the branch from --base (default: the trunk) when it does not exist. The path is derived; none may be given

majordomus worktree create [OPTIONS] [BRANCH]

/docs/cli/worktree/create/ — this command on its own page

Examples

• Start work on a branch without deciding where it goes

  Creates the branch `feature/improve-cli` from the trunk and checks it out in a new worktree at `<repository>-wt/feature/improve-cli`. No path is given and none may be: the destination follows from the repository's identity and the branch name, so the same command in the same repository always produces the same path — from the primary checkout, and from inside another worktree.

  $ majordomus worktree create feature/improve-cli

  Verified by the example tests: exits 0; prints -wt/feature/improve-cli, feature/improve-cli (new.

majordomus worktree ensure

The canonical worktree of a branch: created when absent, answered when present, refused when the branch is checked out somewhere else

majordomus worktree ensure [OPTIONS] <BRANCH>

/docs/cli/worktree/ensure/ — this command on its own page

Examples

• The canonical worktree, whether or not it exists yet

  `ensure` is `create` for a caller that does not care whether the worktree is already there: it creates it when it is absent and answers the existing one when it is present. What a script or an agent runs before starting on a branch.

  $ majordomus worktree create feature/improve-cli
  $ majordomus worktree ensure feature/improve-cli

  Verified by the example tests: exits 0; prints exists, -wt/feature/improve-cli.

majordomus worktree migrate

Bring every misplaced worktree to its canonical path, dirty state included, with a fingerprint taken before and after each move; --plan shows the steps and changes nothing

majordomus worktree migrate [OPTIONS]

/docs/cli/worktree/migrate/ — this command on its own page

Examples

• What it would take to bring every worktree home

  `--plan` shows each misplaced worktree with where it belongs, how it would move, the uncommitted work that moves with it, and what blocks it, and changes nothing. Without `--plan` the movable steps are carried out: each worktree is fingerprinted, moved with `git worktree move`, fingerprinted again at its new path, and reported as moved only when the two are equal.

  $ majordomus worktree migrate --plan

  Verified by the example tests: exits 0; prints nothing to migrate.

majordomus worktree validate

Every error of the topology, and nothing else; exit 10 when there is one

majordomus worktree validate [OPTIONS]

/docs/cli/worktree/validate/ — this command on its own page

Examples

• Is the topology valid?

  Every error-level diagnostic and nothing else, then the verdict; exit 10 when there is an error. What a script gates on.

  $ majordomus worktree validate

  Verified by the example tests: exits 0; prints worktree topology: valid.

majordomus worktree doctor

Every diagnostic of the topology, errors, warnings and facts, each with its code and remedy; exit 10 when there is an error

majordomus worktree doctor [OPTIONS]

/docs/cli/worktree/doctor/ — this command on its own page

Examples

• Every diagnostic, with its code and its remedy

  Errors, warnings and facts — a misplaced worktree, a stale registration, a detached HEAD, the primary checkout off the trunk, an unknown trunk — each under a stable code the API and the Cockpit carry too, each with the command that addresses it.

  $ majordomus worktree doctor

  Verified by the example tests: exits 0; prints worktree topology: valid.

majordomus worktree guard

May a mutation proceed from here? Exit 0 in a canonical worktree, in the primary checkout on the trunk, or detached; exit 10 with the reason otherwise. What the pre-commit hook asks

majordomus worktree guard [OPTIONS]

/docs/cli/worktree/guard/ — this command on its own page

Examples

• May a commit proceed from here?

  The pre-commit hook's question. Exit 0 in a branch's canonical worktree, in the primary checkout on the trunk, or on a detached HEAD; exit 10 with the diagnostic and the remedy when a feature branch is being worked on somewhere it does not belong. The hook stays one line; this is the logic.

  $ majordomus worktree guard

  Verified by the example tests: exits 0; prints worktree guard: ok.

majordomus worktree repair

Drop git's registrations of worktrees whose directories are gone, and repair the administrative links of the ones that exist. Deletes no directory

majordomus worktree repair [OPTIONS]

/docs/cli/worktree/repair/ — this command on its own page

Examples

• What git would forget

  `repair` drops git's registrations of worktrees whose directories no longer exist and lets git repair the administrative links of the ones that do. It deletes no directory and touches no branch; `--dry-run` reports what it would drop and changes nothing.

  $ majordomus worktree repair --dry-run

  Verified by the example tests: exits 0; prints nothing to prune.

majordomus worktree remove

Remove one linked worktree by branch or path. Never the primary checkout, never a branch, never uncommitted work without --force

majordomus worktree remove [OPTIONS] <SELECTOR>

/docs/cli/worktree/remove/ — this command on its own page

Examples

• Remove a worktree, and keep its branch

  Removes the worktree and nothing else. The branch it held still exists: worktree lifecycle and branch lifecycle are separate, and deleting a branch is a git command a person types deliberately. A worktree with uncommitted work is refused rather than removed.

  $ majordomus worktree create feature/improve-cli
  $ majordomus worktree remove feature/improve-cli

  Verified by the example tests: exits 0; prints removed, feature/improve-cli still exists.

majordomus worktree cleanup

The branches merged into the trunk whose worktree is clean or absent: what could be removed. Removes nothing

majordomus worktree cleanup [OPTIONS]

/docs/cli/worktree/cleanup/ — this command on its own page

Examples

• What could go, and what it would take

  Every branch merged into the trunk whose worktree is clean or absent, with the two commands that would remove the worktree and then the branch. Derived state only: nothing is deleted here, and a dirty or unmerged worktree is never listed.

  $ majordomus worktree cleanup

  Verified by the example tests: exits 0; prints cleanup-eligible.

majordomus worktree branches

Every local branch, one per line, for a shell completion that wants the live set

majordomus worktree branches [OPTIONS]

/docs/cli/worktree/branches/ — this command on its own page

Examples

• The live branch set, for completion

  Every local branch, one per line, nothing else. A shell completion for `worktree path`, `create` or `remove` reads this rather than a list kept anywhere, so a branch created a second ago completes.

  $ majordomus worktree branches

  Verified by the example tests: exits 0.

majordomus product

The product: what this repository's tool does for a person, as the features under the layer declare it, with every surface, count and moment derived; the matrix of features against interfaces; the providers; and the model's own validation

majordomus product [OPTIONS] [COMMAND]

/docs/cli/product/ — this command on its own page

Subcommands: list, show, matrix, providers, validate.

Examples

• What the product does, as the layer declares it

  `product` with nothing after it lists the features, because listing is what a person wants when they ask what the tool is for. Every column is derived: the surfaces a feature is exposed through come from the modules, commands and kinds it names, never from the file.

  $ majordomus product

  Verified by the example tests: exits 0; prints SLUG, SURFACES, feature(s).

majordomus product list

Every feature, narrowed by any filter, with the surfaces derived for each

majordomus product list [OPTIONS]

/docs/cli/product/list/ — this command on its own page

Examples

• Every stable feature, in presentation order

  Drafts are excluded unless `--all` is given; `--featured` narrows to the features the homepage shows. The filters are the facets the model derives — an area, a module, a command, a surface — so a module added to the executable is a filter without anything being registered.

  $ majordomus product list

  Verified by the example tests: exits 0; prints SLUG, fixture-feature.

• The same, as the shape the API and MCP answer with

  One domain model behind every projection: this document is what `GET /api/v1/product/features` returns and what the `majordomus_features` tool answers, with the counts, the fingerprint and the surfaces of every feature.

  $ majordomus product list --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /counts/features, /features/0/surfaces, /fingerprint.

majordomus product show

One feature in full: what it is made of, resolved, and everything derived from that

majordomus product show [OPTIONS] <ID>

/docs/cli/product/show/ — this command on its own page

Examples

• One feature, with everything derived from what it names

  The record as its file declares it, then what nobody authored: the capabilities of its modules with their tools and routes, the commands with their summaries, the objects of its kinds counted, the rules with their class, the documents, the decisions, the claims with their status, the moments it answers, and the interfaces all of that adds up to.

  $ majordomus product show fixture-feature

  Verified by the example tests: exits 0; prints fixture-feature, surfaces, derived.

majordomus product matrix

Every feature against every interface, and every module, command and kind against the features that name it

majordomus product matrix [OPTIONS]

/docs/cli/product/matrix/ — this command on its own page

Examples

• Every feature against every interface, and what no feature names

  One row per feature with a mark per surface, then every module of the executable, every public command and every kind of the layer with the features that name it. A row with no feature is a gap the product page cannot hide.

  $ majordomus product matrix

  Verified by the example tests: exits 0; prints FEATURE, cli, MODULE.

majordomus product providers

Every provider the tool has an adapter for, with what this repository does with it

majordomus product providers [OPTIONS]

/docs/cli/product/providers/ — this command on its own page

Examples

• Every provider the tool has an adapter for

  One line per template the distribution ships, with the bootstraps this repository's policy renders through it, the client configuration it carries for the shared MCP server, and the hooks the policy wires. The set is the templates; nothing here is a list of vendors.

  $ majordomus product providers

  Verified by the example tests: exits 0; prints PROVIDER, agents.

majordomus product validate

Every finding over the model; exit 10 when any is an error

majordomus product validate [OPTIONS]

/docs/cli/product/validate/ — this command on its own page

Examples

• Check the model before anything projects it

  A reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a draft that is featured; a stable feature under its floors; and every module, command or kind no feature names. Exit 10 on any error.

  $ majordomus product validate

  Verified by the example tests: exits 0; prints feature(s), valid.

majordomus release

What this project has shipped and what it would ship next: the changelog derived from the layer's own records, the version the two writers state, and the one command that raises both

majordomus release [OPTIONS] [COMMAND]

/docs/cli/release/ — this command on its own page

Subcommands: changelog, version, bump.

Examples

• What has shipped, and what has not

  `release` with nothing after it renders the changelog. Every line of it is derived — a section per release the layer records, its decisions the ADRs dated inside that release's window, its changes the conventional commits in its range — so there is no file anyone can forget to update.

  $ majordomus release

  Verified by the example tests: exits 0; prints Changelog.

majordomus release changelog

The changelog, composed from the layer's release records, the decisions dated inside each release's window, and the conventional commits in its range

majordomus release changelog [OPTIONS]

/docs/cli/release/changelog/ — this command on its own page

Examples

• The same document every other surface answers with

  What `GET /api/v1/changelog` returns, what the MCP resource `majordomus://changelog` carries, and what `majordomus generate changelog` writes into the reference. One value, four renderings.

  $ majordomus release changelog --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /schema, /current, /sections.

majordomus release version

The version the two writers state, whether they agree, and the bump the commits since the last release imply

majordomus release version [OPTIONS]

/docs/cli/release/version/ — this command on its own page

Examples

• The version, and the one the commits imply

  The version is stated in two files for a reason the release script gives: an installed tree has no Cargo.toml and the crate is compiled before the shell tool exists, so neither can read the other at run time. This says what both state, whether they agree, and what the conventional commits since the last release imply the next one should be.

  $ majordomus release version --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /declared, /agree, /bump.

majordomus release bump

Raise the version in both places at once, to the bump the commits imply or to one you name

majordomus release bump [OPTIONS]

/docs/cli/release/bump/ — this command on its own page

Examples

• Raising it, in both places, once

  The bump defaults to what the commits imply — a breaking change is major, a feature is minor, anything else is patch — and `--level` or `--exact` overrides that when a person means something the commits do not say. It writes both files and nothing else; `scripts/release-version --check` then proves the work of one writer rather than the memory of one person. A repository that declares no version — the example runs in one with no crate — cannot be raised, and says so with exit 12 rather than inventing a number to raise from.

  $ majordomus release bump --dry-run

  Verified by the example tests: exits 12.

majordomus quality

What this executable's own public surface is held to: documentation, executable examples, module coverage, and every command accounted for against the capability registry

majordomus quality <COMMAND>

/docs/cli/quality/ — this command on its own page

Subcommands: report.

Arguments: none.

majordomus quality report

Measure the crate and report every finding, with the rule it breaks and what to do about it

majordomus quality report [OPTIONS]

/docs/cli/quality/report/ — this command on its own page

Examples

• Where the crate's public surface stands

  The counts alone: how much of the exported surface is documented and exampled, how many modules something exercises, and how the canonical operations stand against the command line, HTTP, OpenAPI and MCP. Exits 10 when any finding stands outside the recorded baseline.

  $ majordomus quality report --summary

  Verified by the example tests: exits 0.

• One kind of finding, with the rule and the remedy

  Filtered to one violation code. Every finding carries the rule that requires it, where it is, why it matters and what to do — which is what lets a person and an agent act on the same report.

  $ majordomus quality report --code RUST_MODULE_MISSING_EXAMPLE --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /measured, /passes, /report/schema.

majordomus run

Run a capability as an execution and follow it: its steps, its progress and its output as they happen

majordomus run [OPTIONS] <CAPABILITY>

/docs/cli/run/ — this command on its own page

Examples

• Watch an execution happen

  `run` starts a capability as an execution and follows it to its end: every step, every line it logs and every advance of its progress, as the handler reports them. `executions.demonstrate` exists to make that visible without waiting for real work — it reads nothing and writes nothing, and its only effect is the events it produces. The same execution, started from the Cockpit, streams the same events to a browser.

  $ majordomus run executions.demonstrate --input '{"steps":2,"delay_ms":0}' --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /state, /id, /output/steps, /steps/0/name.

majordomus executions

The executions of the server serving this repository: what has run, what is running, and what each one said

majordomus executions [OPTIONS] [COMMAND]

/docs/cli/executions/ — this command on its own page

Subcommands: list, show, events, cancel, protocol.

Examples

• What has run

  `executions` with nothing after it lists what the server serving this repository has run, newest first. In a checkout where no server is running it says so rather than pretending: an execution lives in the process that accepted it.

  $ majordomus executions

  Verified by the example tests: exits 0; prints execution.

majordomus executions list

Every execution the server remembers, newest first

majordomus executions list [OPTIONS]

/docs/cli/executions/list/ — this command on its own page

Examples

• Every execution, as one document

  The same answer `GET /api/v1/executions`, the MCP tool `majordomus_executions` and the Cockpit's Executions page render, with the counts beside it: how many are remembered, how many are active, how many are waiting for a worker and how many live channels are following them.

  $ majordomus executions list --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /count, /active, /queued, /live_channels.

majordomus executions show

One execution in full: its state, its steps, its diagnostics and what it produced

majordomus executions show [OPTIONS] <ID>

/docs/cli/executions/show/ — this command on its own page

Examples

• An execution that is not there

  An execution lives in the process that accepted it and is remembered in bounded numbers, so asking for one nothing ran says so and exits with the missing-artifact code rather than inventing an empty answer. Against a running server, the same command prints that execution's state, its steps and what it produced.

  $ majordomus executions show x-20260101T120000Z-4c3b2a19

  Verified by the example tests: exits 12.

majordomus executions events

One execution's retained events, oldest first

majordomus executions events [OPTIONS] <ID>

/docs/cli/executions/events/ — this command on its own page

Examples

• The events of an execution that is not there

  The retained events of one execution, oldest first, after a sequence number — what a reconnecting client reads before it opens the live channel. For an execution nothing ran, the same refusal as `show`.

  $ majordomus executions events x-20260101T120000Z-4c3b2a19

  Verified by the example tests: exits 12.

majordomus executions cancel

Ask an execution to stop

majordomus executions cancel [OPTIONS] <ID>

/docs/cli/executions/cancel/ — this command on its own page

Examples

• Asking an execution that is not there to stop

  Cancellation is cooperative: the flag is set and a task stops when it next looks at it. There is nothing to set for an execution nothing ran, and the command says so rather than reporting a success it did not have.

  $ majordomus executions cancel x-20260101T120000Z-4c3b2a19

  Verified by the example tests: exits 12.

majordomus executions protocol

The live channel's contract: where it is, what it writes, and the schema of each message

majordomus executions protocol [OPTIONS]

/docs/cli/executions/protocol/ — this command on its own page

Examples

• The live channel's contract, from the types that implement it

  Where the WebSocket is, how a subscription and a reconnect are expressed, every message type, and the JSON Schema of each — derived from the Rust types, so a client validating against this is validating against the implementation. OpenAPI cannot describe a socket, which is why this is a capability and not a paragraph.

  $ majordomus executions protocol --format json

  Verified by the example tests: exits 0; prints one JSON document carrying /protocol_version, /websocket, /event_types/0, /stream_types/0, /limits/max_events.