CLI reference

The mint command inspects declarations, runs the broker, and records safe operator state. It never prints stored credential values except for a newly issued capability token.

Run mint --help or mint <command> --help to inspect the live parser.

Choose a job

Job	Command group	Use it for
Run or assess the broker	serve, doctor	Start the broker or check its effective startup inputs.
Check declarations	policy check, alias list	Validate policy and inspect alias names.
Inspect the ledger	audit ...	Read, reconcile, migrate, or verify audit records.
Manage local capabilities	capability ...	Issue, list, or revoke loopback development capabilities.
Measure adoption	adoption ...	Read declarations and scan configured consumer surfaces.
Manage releases	release ...	Digest, validate, preflight, and activate a staged release.
Record local cutover	local-cutover ...	Advance a durable, value-free cutover journal.

All examples use synthetic paths. Create those files before running a command.

Run and assess the broker

mint serve

Start the long-running broker.

MINT_BIND_ADDR=127.0.0.1:4949 MINT_POLICY_PATH=./examples/policy.yaml MINT_CALL_GUARDS_PATH=./examples/call-guards.yaml MINT_CAPABILITIES_PATH=./examples/capabilities.yaml MINT_ALIASES_PATH=./examples/aliases.yaml MINT_AUDIT_LOG_PATH=./examples/audit.log MINT_AUTH_MODE=shared-secret MINT_SECRET_BACKEND=env mint serve

The four parser-path flags are all required together when you supply one. Omit all four to use the environment-selected paths.

The explicit capabilities file must contain no entries for tailnet authentication. The process serves the HTTP routes until it receives SIGTERM or SIGINT. A SIGHUP reloads policy and capability declarations as one snapshot. A startup or serving error exits nonzero.

mint doctor

Check the effective startup configuration without inspecting a running broker.

mint doctor --policy-path ./examples/policy.yaml --call-guards-path ./examples/call-guards.yaml --capabilities-path ./examples/capabilities.yaml --aliases-path ./examples/aliases.yaml --self-test-alias secret://example/default

The path flags follow the same all-or-nothing rule as serve. Each check prints one JSON object. The self-test resolves an alias for pass or fail and never prints its value. Omit --self-test-alias to report that check as skipped. A failed check makes the command exit nonzero.

Check declarations

mint policy check FILE

Parse and validate one policy YAML file.

mint policy check ./examples/policy.yaml

Success prints a rule count, default effect, and legacy call-limit count. Legacy policy limits also produce a deprecation message on stderr. Invalid input prints INVALID on stderr and exits nonzero.

mint alias list [--path FILE]

List alias names and descriptions without resolving them.

mint alias list --path ./examples/aliases.yaml

The default path is MINT_ALIASES_PATH or .mint/aliases.yaml. Each entry is tab-separated as alias and description. An empty registry prints a no-alias message.

Inspect the audit ledger

The default audit path is MINT_AUDIT_LOG_PATH or .mint/audit.log. Every audit command below reads or appends value-free records.

mint audit tail

Print the last events, oldest first.

mint audit tail -n 20 --actor example-agent --path ./examples/audit.log

Use -n or --n to set the count. Use --actor to select one caller. Each event prints as one JSON line.

mint audit reconcile EFFECT_ID

Append an indeterminate terminal record for one interrupted prepared effect.

mint audit reconcile 00000000-0000-4000-8000-000000000001 --path ./examples/audit.log --reason operator-reviewed-no-retry --operator example-operator

The effect identifier must be a UUID. The reason and operator values must not be empty. The command never retries the upstream request or claims success. Success prints a tab-separated RECONCILED line.

mint audit unresolved

List prepared effect identifiers that have no terminal record.

mint audit unresolved --path ./examples/audit.log

The command prints one identifier per line.

mint audit migrate

Perform the explicit one-time migration from a legacy ledger.

mint audit migrate --path ./examples/audit.log --reason legacy-ledger-reviewed --operator example-operator

The reason and operator values must not be empty. The command prints a tab-separated MIGRATED line. A second migration attempt against a chained ledger fails.

mint audit verify

Verify the complete audit hash chain.

mint audit verify --path ./examples/audit.log

Success prints one sanitized JSON report. Mutation, deletion, reordering, or duplication makes the command exit nonzero.

Manage loopback capabilities

mint capability issue

Issue a capability declaration and print its raw bearer once.

mint capability issue --path ./examples/capabilities.yaml --actor example-agent --workspace example-workspace --expires-at 2030-01-01T00:00:00Z

The saved declaration stores only a hash and metadata. The JSON result contains the one-time token. Do not copy that result into logs, prompts, files, or tickets.

mint capability list

Print capability metadata without tokens or token hashes.

mint capability list --path ./examples/capabilities.yaml

Each entry prints JSON with its id, actor, workspace, audience, and expiry.

mint capability revoke

Revoke one declaration by id.

mint capability revoke --path ./examples/capabilities.yaml --id capability-example-001

An unknown id fails before the file is saved. Success prints the revoked metadata as JSON.

Measure adoption

mint adoption report

Report totals and each consumer's evidence-derived posture.

mint adoption report --path ./examples/adoption.yaml

The first line prints totals for brokered, direct, mixed, unverified, and parked entries. Following lines print a consumer name, substrate, status, and reason.

mint adoption scan

Scan agent configuration files for raw or runtime credential material.

mint adoption scan --boundaries ./examples/credential-boundaries.yaml
mint adoption scan ./examples/agent-config.yaml

Use --boundaries to load declared scan paths and allowed environment names. Pass files or directories when no boundary inventory is supplied. The scan rejects missing paths, symlinks, and empty scan sets. It prints each file report and exits nonzero for any violation.

mint adoption discover

Discover installed launcher homes without reading their values.

mint adoption discover --home ./examples/home

The default home is $HOME. The output reports the inspected home, launcher count, and violation count. It prints value-free findings and exits nonzero for an unclassified surface.

mint adoption cutover-check

Compare a cutover manifest with an environment-name inventory.

mint adoption cutover-check --manifest ./examples/cutover.yaml --env-file ./examples/environment.names --aliases ./examples/aliases.yaml --stage inventory

The stage is inventory or name-state. The command compares names only and never prints values. Drift is reported as UNDECLARED, ABSENT, or STILL_PRESENT on stderr. Exact coverage prints an OK line.

Manage releases

Release commands operate on a staged candidate selected by the running binary. Use synthetic paths in review or local checks.

mint release digest BUNDLE

Hash a fixed-shape bundle.

mint release digest ./examples/mint-release

Success prints the bundle digest.

mint release credential-metadata ALIASES

Print names-and-IDs-only credential metadata derived from an alias file.

mint release credential-metadata ./examples/aliases.yaml

Success prints one JSON document. It does not print credential values.

mint release validate BUNDLE

Validate a staged bundle with the linked parsers.

mint release validate ./examples/mint-release

Success prints a JSON preflight receipt. Activation repeats preflight against the candidate.

mint release preflight

Validate the immutable bundle containing the running candidate binary.

mint release preflight

Success prints one JSON receipt. The command fails when the binary is not inside a valid staged bundle.

mint release systemd-contract

Validate the effective service command contract.

mint release systemd-contract

The command reads the effective service command and prints systemd contract ok on success. It fails when the service command cannot be read or does not match the contract.

mint release activate --expected-old TARGET

Atomically activate a staged candidate with an expected previous target.

mint release activate --expected-old releases/previous-example

Activation requires root and a rollbackable previous target. The candidate must be staged by the release layout. Success prints a JSON activation receipt.

Record a local cutover

Every local-cutover command takes a journal and transaction id. The journal stores sanitized state, counts, timestamps, references, and evidence.

mint local-cutover discover

Create or reopen a journal at its discovered state.

mint local-cutover discover --journal ./examples/cutover-journal.json --transaction-id example-transaction

Success prints the sanitized snapshot as JSON.

mint local-cutover transition

Append one forward phase and its sanitized evidence.

mint local-cutover transition --journal ./examples/cutover-journal.json --transaction-id example-transaction --next-state staged --actor example-operator --summary staged-example --reference https://example.com/evidence/example

The state is one of staged, broker-proven, egress-locked, sources-sanitized, or awaiting-rotation. Invalid transitions or evidence fail without advancing the journal. Success prints the updated sanitized snapshot.

mint local-cutover rollback-contained

Stop a transaction in containment.

mint local-cutover rollback-contained --journal ./examples/cutover-journal.json --transaction-id example-transaction --reason example-review-stop

The rollback does not restore raw material. Success prints the updated sanitized snapshot.

mint local-cutover commit

Commit a fully advanced transaction with severance metadata.

mint local-cutover commit --journal ./examples/cutover-journal.json --transaction-id example-transaction --source-count 2 --sanitized-count 2 --path ./examples/source-a --class example-credential --artifact-digest receipt=0000000000000000000000000000000000000000000000000000000000000000

Repeat --path, --class, and --artifact-digest for multiple entries. Each digest must be 64 lowercase hexadecimal characters. Success prints the updated sanitized snapshot.

mint local-cutover show

Print a journal snapshot without changing it.

mint local-cutover show --journal ./examples/cutover-journal.json --transaction-id example-transaction

The JSON contains state, transaction id, timestamps, sanitized counts, and references.

Source map

The parser, complete dispatch, and command implementations are pinned in main.rs command declarations, main.rs dispatch, and main.rs implementations. Broker startup, graceful signals, and declaration reload are pinned in broker lib.rs. The CLI's local-cutover, adoption, and release contracts are pinned in local_cutover.rs, cutover.rs, adoption.rs, and release.rs. Audit and capability output contracts are pinned in main.rs output functions.