Command reference #
The nomarmy CLI #
Every command proposes before it writes: a [y/N] prompt, or an explicit flag under --json. All take --json and --repo <dir>.
| Command | What it does |
|---|---|
nomarmy doctor | Checks this machine is ready, with a fix for anything missing. Start here. |
nomarmy setup | The setup playbook: a checklist of where models run, install, agents, roles, this repo and a check, running the next step when you say yes. --status prints it only; --choose, --hosted and --llama-url set where models run. |
nomarmy sandbox | The Podman VM every sandbox shares (macOS; on Windows Podman runs inside WSL, sized by .wslconfig): memory, disk and images. --memory <GiB> resizes it (refused while jobs run, below 4 GiB, or above three quarters of the machine); --prune removes images no container uses; --repair restores rootless Podman's subordinate ID ranges if they're missing (refused while jobs run). |
nomarmy install | Runs the bundled install.sh for the profile setup chose (--profile to override, --no-claude to skip the Claude Code registration). |
nomarmy connect [claude] [codex] [cursor] [--scope user|local|project] | Registers nomArmy with each coordinator and installs /feature, the status line and the notifier. No target: pick interactively. --scope local registers it for this repository only, just for you; --scope project writes a committed .mcp.json or .cursor/mcp.json for the team (see Per-repository registration). Codex has only the user scope. |
nomarmy stats [--since 7d|<date>] [--until <date>] [--role <role>] [--model <model>] [--repo <path|name>] [--all-repos] [--details] [--all-suggestions] [--json] | One screen by default: how many "done, tests pass" claims held up and how many nomArmy caught, new tests shown to fail without their change, committed high-stakes jobs still needing a review, the top routing tips, and spend. --details adds everything the records show: jobs by mode, role and model; code committed; worker and job time; tokens and API spend; how often a "done, tests pass" report failed independent verification or passed with tests that couldn't catch the change; what didn't complete; reviewers; review flags. From verified records, never reports. --repo senti matches a repository by folder name. The General gets the same through the stats tool. |
nomarmy validators <list|add jev|test jev|remove jev> | Optional semantic checks with your own key: Jev judges whether a scout's cited lines support its finding and whether a worker's report matches its diff. Only adds review flags; sends code excerpts to TypeSafe. See Validators. |
nomarmy validators <add judge --agent <name> --model <model> [--host-tools]|test judge|remove judge> | Makes one of your agents a model judge for implement jobs: acceptance criteria, report vs. diff, weakened tests. Only adds review flags. An agent whose tools run on your machine needs --host-tools. See Validators. |
nomarmy jobs --stop <job> [--reason <text>] | Stops a running job's worker, keeping its worktree for continue_from. |
nomarmy mcp | Starts nomArmy's MCP server on stdio with this machine's settings: what a --scope project registration runs. |
nomarmy init | Proposes a .nomarmy.yml from what the repo contains. |
nomarmy agents list|add|update|remove | Where jobs can run. See Agents. |
nomarmy army show|init|assign|general | The General and the roster. See The army. |
nomarmy jobs [--watch|--events|--prune|--wait <jobId>] | What's running across every session, and what just finished. --wait <jobId> [--timeout <seconds>] waits for one cross-session job (default 1800 seconds; add --json for structured output). |
nomarmy health | Runs the health checks now. |
nomarmy statusline | nomArmy's part of Claude Code's status line. |
nomarmy config paths | Where each config file lives. |
nomarmy config max-jobs [n] | How many api and subscription jobs run at once, across every session (default 4); with n, sets it. Warns when the Podman VM is too small. |
nomarmy model | Changes the local model. |
nomarmy sizing | Recommends context, slots and workers. --check evaluates the loaded profile; --noms N sizes for a count. |
nomarmy start / stop | Starts or stops local inference. |
nomarmy scan | Reports the repo's execution environment. --check diffs it against .nomarmy.yml. |
nomarmy acceptance fill <run-id|job-id> [--dry-run] [--json] | Appends verified jobs' proposed tests to contract proofs without removing existing entries or comments. Skips duplicates; marks unproven criteria met only after their proofs pass in the same sandbox runner as the PR Acceptance row, using the working tree and a read-only snapshot of the proposed proofs. If the sandbox cannot verify, proposals are still appended, statuses stay unchanged, and the command says it could not verify. --dry-run previews without writing. |
nomarmy acceptance check [file...] [--json] [--strict] | Runs this repository's tests on this machine, like npm test, selecting those named by each criterion in the feature contracts under acceptance/ (or selected files). Reports met, broken, missing or unproven per criterion; --json prints the report as data, and --strict also fails on unproven. |
nomarmy validate | Validates .nomarmy.yml. |
nomarmy update | Updates nomArmy and reconnects every coordinator it finds. From npm: installs the latest alpha. From a clone: pulls (fast-forward only). Then it names each open session still running an older nomArmy (app, terminal, start time) so you know which to restart; until you do, army and local_worker_capacity say so, and nomarmy health flags a coordinator still running an older copy. |
nomarmy uninstall | Removes the MCP registration and install. --clear-agents, --clear-models or --all go further. |
Acceptance contract format and execution #
Write one acceptance/<feature>.yml at plan time, with stable criterion IDs for durable promises, not job hygiene. Assign those IDs in each implement job brief through criteria before dispatch, including parallel jobs. Each criterion has id, text, status (met, unproven, broken or retired) and proven_by. Proofs may be { file: tests/example.test.mjs, test: "exact test name" }, { command: "npm run build", cwd: packages/example }, or { manual: "real install", checked_by: "Reviewer Name", date: "2026-09-30", expires_days: 90 }. cwd and expires_days are optional. Any proof may set platforms: [win32] or another Node process.platform value; posix means every platform except win32. Out-of-platform proofs do not run. Current manual proof is reported as manual and can meet a criterion; expired proof is unproven with a note and cannot override broken automated evidence.
nomarmy acceptance check [file...] [--json] [--strict] checks all contracts or selected files, reports each criterion and fails on broken or missing proofs; --strict also fails on unproven. CI runs it on every platform job. Every automatic check runs in the sandbox, never on the host. After integrating a run, use nomarmy acceptance fill <run-id> --dry-run, prune unrelated proposed mappings, then fill for real and commit the contract with the feature. A CONTRACT BROKEN: issue requires fixing the change or intentionally changing the contract in the same pull request.
Acceptance checks for affected criteria require review when a promise breaks, but do not by themselves block nomArmy's commit on the worker's branch. Integration is the gate. Changed contract files are separately checked with --strict: unproven criteria fail verification (current manual proofs count as met). Removing or retiring a criterion, removing proofs, or downgrading met to unproven records CONTRACT WEAKENED and requires review; adding criteria or proofs is not weakening.
MCP tools #
What the General uses. Every job takes the same shape: a task, optional acceptance and contract criteria IDs (implement only), a mode and a timeout.
| Tool | What it does |
|---|---|
local_worker | Runs one job and waits for it. |
local_worker_start / local_worker_status | Starts a job in the background / waits for its result. The start response includes nomarmy jobs --wait <jobId> for background monitoring. report: true returns just the report (a scout's cited findings), the outcome, issues and commit; full: true the whole record. Timeouts default to 10 minutes, 20 for a review scout (reviews set, or a review-phase role). |
local_workers | Runs a batch of independent jobs in parallel. auto_union: true merges them into one integration branch for review. |
repo_evidence | Deterministic answers (definitions, references, outlines, grep, files) with [path:line] on every hit, no model. |
army | The General's charter and agent, then this repo's roles and who runs each. |
run_start / run_status / run_finish | A /feature run: its limits, usage per agent, warnings, paused agents and log. |
local_worker_capacity | Context, budgets, memory pressure and what's running. |
local_worker_stop | Stops a running job's worker (no report recovery, no verification) and keeps its worktree for continue_from. Works for any session's job. |
stats | What the job records show for this repo (or all_repos, or another repo by name), filtered by since, until, role and model; format: json for the raw numbers. |
local_worker_jobs | Recent job records; full: true for the complete manifest. |
local_worker_config | This repo's verification profiles. |
local_worker_cleanup | Removes one worktree and branch. Recognizes a cherry-picked branch as integrated by content. |
local_worker_sweep | Removes worktrees that are provably empty. dry_run previews. |
A job's mode is implement (edits, then nomArmy verifies and commits), scout (read-only research, every claim cited as [path:start-end] and checked against the base commit) or decompose (read-only, proposes independent subtasks for the General to dispatch).