Command Reference

Command Reference

All commands are subcommands of repo-steward. Flags follow the positional argument. Every command that runs the sandbox takes the executor lock, so one inspection or maintenance run executes at a time per data directory.

Exit codes

Code	Meaning
0	proposal prepared or published; or the command succeeded
1	an error before or during the run, printed to stderr
2	the repository is unsupported; the refusals are in the report
3	the baseline is failing or inconclusive; nothing was attempted
4	an explained non-result: regression, blocked, scope exceeded, budget or limit exhausted, rejected
5	the run paused for an approval; see approve, reject, and resume
6	maintain only: the upgrade could not be fetched because the module proxy or checksum database was unreachable or failed (acquisition_failed); a later run may succeed

vulns has its own codes for 3 and 4, listed under vulns. maintain -select vulnerable ends scan_inconclusive, no_vulnerabilities, and no_fix_available as explained non-results, so they exit 4.

Note that go run reports every non-zero exit as 1. Build the binary when you need the codes.

inspect

repo-steward inspect <repo-path> [-data-dir DIR] [-fixture-proxy DIR] [-pull] [-allow-major] [-dependency MODULE[@VERSION]] [-min-age DURATION] [-check-timeout DURATION]

Profiles the repository at HEAD, materializes an exact snapshot, populates the module cache, discovers candidates, and validates the baseline. Makes no model call and no mutation. The working tree may be dirty; the report says so and uses HEAD's tree. -min-age is the version cooldown, see below.

vulns

repo-steward vulns <repo-path> [-data-dir DIR] [-fixture-proxy DIR] [-vulndb DIR] [-pull] [-scan-timeout DURATION]

Reports the known vulnerabilities that affect the repository at HEAD, and changes nothing. It prints a JSON report on stdout and a short summary on stderr. Exit codes: 0 when the scan is conclusive and finds nothing in third-party dependencies (standard-library findings alone still exit 0, because they follow the toolchain image and cannot be acted on), 1 on an error, 2 unsupported, 3 inconclusive, 4 third-party findings present. -vulndb DIR uses an existing database directory instead of fetching https://vuln.go.dev; -scan-timeout defaults to 10 minutes. Needs the container engine and network access as described in Vulnerabilities: Reporting and Fixing.

maintain

repo-steward maintain <repo-path> -mode baseline|scripted|model
    [-scenario NAME] [-model provider:name] [-record DIR] [-replay DIR] [-max-model-calls N] [-max-cost-usd USD]
    [-author "Name <email>"] [-data-dir DIR] [-fixture-proxy DIR] [-pull]
    [-allow-major] [-dependency MODULE[@VERSION]] [-min-age DURATION]
    [-select smallest|vulnerable [-vulndb DIR] [-scan-timeout DURATION]] [-check-timeout DURATION]
    [-scope-files-soft N] [-scope-files-hard N] [-scope-lines-soft N] [-scope-lines-hard N]
    [-publish [-destination owner/repo] [-github-api URL] [-push-url URL]] [-trace]

Flag	Meaning
-mode	baseline: deterministic pipeline, no model. scripted: replay an embedded scenario's decisions. model: a model decides.
-scenario	scenario name for scripted mode, e.g. S2
-model	provider:name; only ollama exists
-record, -replay	capture model responses to a directory, or serve them from one and never call the provider
-max-model-calls	cap on model calls including retries; default 80
-max-cost-usd	cap on estimated model spend, written as 5, 4.41, or $0.50; required for a paid provider
-author	proposal commit author; defaults to the source repository's git user
-allow-major	treat major upgrades as eligible
-dependency	restrict eligibility to one module, or with module@version to one exact version; selection is skipped. Only versions newer than the current one are candidates, so a pin cannot downgrade
-min-age	version cooldown: a version published less than this long ago, or with no known publish time, is ineligible and its candidate entry says why; default 72h; 0 turns it off. Also on inspect. Waived in -select vulnerable for the version that clears an advisory
-select	baseline mode only: smallest (default) or vulnerable, which scans for known vulnerabilities and picks the lowest eligible upgrade that clears them. Scripted and model modes refuse vulnerable with exit 1. See Vulnerabilities: Reporting and Fixing
-vulndb	with -select vulnerable: use this database directory instead of fetching https://vuln.go.dev
-scan-timeout	with -select vulnerable: bound for each scan; default 10 minutes
-scope-*	soft and hard limits on changed source files and lines; see Configuration
-publish	verify the destination now and allow publication after approval; the token is read from GITHUB_TOKEN
-destination	owner/repo on github.com; otherwise parsed from the source's origin remote
-github-api, -push-url	overrides for tests against a fake server and a local bare repository
-trace	print every runtime event to stderr

Outcomes added for fetching and vulnerable selection

Outcome	Exit	Meaning
acquisition_failed	6	go get or go mod tidy failed because the module proxy or checksum database was unreachable (DNS, connection, timeout, TLS) or answered 5xx; the toolchain's message is in the detail. Anything not matched keeps its earlier outcome, such as admission_refused
scan_inconclusive	4	the base scan did not complete cleanly; never read as "no vulnerabilities"
no_vulnerabilities	4	a conclusive scan found nothing in third-party dependencies
no_fix_available	4	nothing eligible clears any finding; a reason is given per finding

Output is a JSON result with the outcome, the selected target, the baseline and post-change validation summaries, the admission and normalization verifications, the readiness report, the proposal, run statistics, and timings.

resume

repo-steward resume <run-id> [-data-dir DIR] [-fixture-proxy DIR] [-pull] [-trace]

Continues a run that is waiting for an approved approval or was left mid-step by a crash. The session is rebuilt from the persisted task, options, candidate facts, and baseline evidence under the same configuration hash. A run that started with a fixture proxy needs -fixture-proxy again. A finished run is refused.

approve and reject

repo-steward approve <run-id> [-approval ID] [-note TEXT] [-by NAME] [-data-dir DIR]
repo-steward reject  <run-id> [-approval ID] [-note TEXT] [-by NAME] [-data-dir DIR]

Decide the run's single pending approval, or a named one. Both go through agent-runtime's approver on the data directory's steward.db: the approval is printed to stderr first, in the sanitised text form of approver/webhook (kind, tool, the policy's reason, expiry, then each argument and presentation field, with model-chosen text escaped so it cannot move the cursor or imitate the prompt), and the decision is bound to the hash of what was printed, so it is refused if the stored approval differs. The runtime also recomputes the approval's hash from its stored fields and refuses a mismatch. A decision on an approval past its expiry is refused and the run is cancelled. reject cancels the run and records the outcome. Neither continues the run; resume does. The JSON on stdout is the decided approval. Without -by, the decision is recorded as $USER, or the account name when that is unset.

cancel

repo-steward cancel <run-id> [-note TEXT] [-by NAME] [-data-dir DIR]

Ends a run that is not finished, without executing anything, as cancelled, through the same approver. A decided approval cannot be rejected, so this is the way to close a run that was approved but never resumed, or one you no longer want. It takes both the executor lock and the run's lock, so it refuses while another process is working on the run. A cancelled run cannot be resumed.

runs

repo-steward runs list [-data-dir DIR]
repo-steward runs show <run-id> [-events] [-data-dir DIR]

list prints every task with its mode, source, outcome, runtime status, step count, and the id of a single pending approval when the run is waiting for one. show prints the task, the run, every step with its tool, decision kind, status, policy verdict, observation kind, and summary, the approvals, the proposals, and the promotions; -events adds the full event log. The run and step rows are the runtime's own read models (view.Summary, view.Steps), so their field names match agentrt's operator output; the task, proposal, and promotion sections are Repo Steward's.

fixture

repo-steward fixture list
repo-steward fixture setup <name> [-dest DIR]
repo-steward fixture proxy [-dest DIR]
repo-steward fixture vulndb [-dest DIR]

setup materializes an embedded fixture into a real Git repository with a fixed commit identity, so the commit id is the same on every machine and is pinned. proxy generates a file-based module proxy for every embedded fixture module.

fixture vulndb -dest DIR writes the synthetic vulnerability database for the fixture modules (the directory must not exist), for use with vulns and -vulndb; it needs no engine.

snapshot

repo-steward snapshot build <repo-path> [-dest DIR] [-max-files N] [-max-bytes N]

Builds the candidate tree from the working tree and materializes it exactly, printing the tree hash, file count, bytes, and whether verification passed. Useful for seeing what validation would see.

bench

repo-steward bench run -mode baseline|scripted|model [-model provider:name] [-scenarios S1,S2,...] [-repeat N]
    [-max-model-calls N] [-max-total-calls N] [-max-cost-usd USD] [-max-total-cost-usd USD] [-root DIR] [-out DIR] [-author "Name <email>"]
repo-steward bench summarize [-dir DIR] [-mixed-commits]

run executes scenarios on fresh fixtures and writes a JSON and a Markdown result file. A paid provider needs -max-cost-usd per run and -max-total-cost-usd; the harness stops before a run whose cap could exceed the total. Result files are in the format of agent-runtime's bench module. summarize renders the latest result per mode and model as one table with every count over its denominator, a per-scenario matrix, each scenario's means across repetitions, and each column's commit and budget settings. It refuses results from different commits unless given -mixed-commits, and then says above the table that they are not comparable as like for like. See Fixtures, Scenarios and Benchmarks.