Skip to content

cli.md

Latest commit

 

History

History
198 lines (151 loc) · 7.41 KB

cli.md

File metadata and controls

198 lines (151 loc) · 7.41 KB
Raw

CLI Reference

The published binary is martin-loop. Public installs, docs, and examples should use martin-loop.

Commands

martin-loop --version
martin-loop start
martin-loop tour
martin-loop doctor
martin-loop demo
martin-loop audit [--days <n>] [--project <text>] [--dir <path>] [--share] [--offline]
martin-loop session-start [--host <claude|codex|gemini|generic>]
martin-loop phase status|contract|session-start|preflight|run [--execute]
martin-loop preflight <objective> [options]
martin-loop run <objective> [options]
martin-loop bench --suite <suiteId>
martin-loop triage
martin-loop dossier (--latest | --loop-id <id> | --file <path>)
martin-loop inspect --file <path>
martin-loop resume <loopId>
martin-loop challenge [--loop-id <id> | --file <path> | --latest] [--format markdown|svg]
martin-loop share (--loop-id <id> | --file <path> | --latest) [--out-dir <path>]
martin-loop badge [--format svg|json] [--runs-dir <path>]
martin-loop runs list|get|attempt|verify ...
martin-loop sync status
martin-loop sync flush
martin-loop mcp print-config --host <codex|claude|gemini|generic>
martin-loop mcp install --host <codex|claude|gemini|generic>

Audit Claude Code Loop Tax

npx -y martin-loop@latest audit
npx -y martin-loop@latest audit --days 30 --json
npx -y martin-loop@latest audit --share
npx -y martin-loop@latest audit --offline

The audit reads Claude Code session history locally. It estimates API-equivalent spend inside fix-and-retry loops and reports verifier failures, retry depth, stuck loops, red-ending sessions, and edited sessions with no recognized verifier command. By default it may fetch the public LiteLLM model-price list; no session contents are sent. Use --offline for zero network access.

Onboarding Flow

Use this sequence when you are new to the product or setting up a fresh repo:

npx -y martin-loop@latest enable --engine codex
npx -y martin-loop@latest start
npx -y martin-loop@latest --version
npx -y martin-loop@latest demo
cd martin-loop-demo
npm install
npx -y martin-loop@latest run "Summarize the workspace and prove tests still pass" --verify "npm test" --budget-usd 2 --max-iterations 1
npx -y martin-loop@latest share --latest

run auto-checks doctor, session-start, and preflight, then executes when the environment is ready. Run those commands directly when you want to inspect the governed checks first.

Run Options

--objective <text>      The task to accomplish, or pass it as the first positional arg
--budget <n>            Hard cost cap in USD
--budget-usd <n>        Alias for --budget
--soft-limit-usd <n>    Soft budget threshold in USD
--verify <cmd>          Verifier command after each attempt
--proof                 Explicitly opt into a no-spend proof adapter lane
--unsafe-allow-unguarded-run
                        Bypass the local governance gate for this one run
--max-iterations <n>    Maximum number of attempts
--max-tokens <n>        Maximum token budget
--engine <name>         Adapter to use: claude, codex, or openai
--model <name>          Override the adapter model
--cwd <path>            Repo root for the run
--allow-path <glob>     Restrict writes to this path pattern; repeatable
--deny-path <glob>      Block this path pattern; repeatable
--accept <criterion>    Add an acceptance criterion; repeatable
--config <path>         Path to a martin.config.yaml file
--workspace <id>        Workspace ID for the run record
--project <id>          Project ID for the run record
--metadata <key=value>  Attach metadata to the run record; repeatable

Inspect-First Flow

npx -y martin-loop@latest enable --engine codex
npx -y martin-loop@latest doctor
npx -y martin-loop@latest session-start
npx -y martin-loop@latest preflight "fix the auth regression" --verify "pnpm test"

Benchmark Reproduction

Use bench when you want the shipped public benchmark summary from an installed package:

npx martin-loop bench --suite under-3-challenge
npx martin-loop bench --suite ralphy-engineering-50

Use the public benchmark workspace when you want clean-clone repro from the repository:

pnpm install --frozen-lockfile
pnpm --filter @martin/benchmarks build
pnpm --filter @martin/benchmarks test
pnpm --filter @martin/benchmarks eval
pnpm --filter @martin/benchmarks report:ralphy

Shared persisted-run options

--runs-dir <path>       Override the Martin runs root for guided flow receipts, persisted evidence views, and badge generation
--out-dir <path>        Override where `martin share` writes the local share bundle

Hosted sync

sync status reports queued hosted evidence. sync flush attempts to upload eligible queued records using:

MARTIN_API_TOKEN             Workspace-scoped hosted API token
MARTIN_TELEMETRY_ENDPOINT    Hosted telemetry endpoint

Both settings are required for a flush. Missing configuration returns a nonzero exit and preserves the queue. A later configured flush uploads the same run ID; normal governed execution and local receipt verification remain independent of hosted availability. Keep tokens in environment or secret-management facilities and never print them.

Evidence Commands

Use triage first when you want the fastest ranking of saved runs:

npx martin-loop triage

Use dossier when you want one run receipt:

npx martin-loop dossier --latest

Compatibility views remain available:

npx martin-loop inspect --file ~/.martin/runs/<workspaceId>.jsonl
npx martin-loop resume <loopId>
npx martin-loop challenge --latest
npx martin-loop share --latest
npx martin-loop badge --format json --runs-dir ~/.martin/runs

Evidence-readiness badge

martin badge reports how many of five binary local evidence signals are present:

  1. a configured budget;
  2. a configured verifier;
  3. a persisted run receipt with verified integrity;
  4. rollback, restore, or patch evidence; and
  5. passing local MCP doctor prerequisites.

The human result and full --json document report N/5 signals and explain every missing signal. --format svg emits an SVG badge, while --format json emits the compact four-field Shields static-endpoint document.

A 5/5 result means all five local evidence signals are present. It is not a historical success rate, probability, benchmark result, or claim that agent runs succeed 100 percent of the time. The retained points and maxPoints fields are compatibility readiness points, with 20 points assigned to each present signal.

Share command

Use share when you want a reviewable bundle for the latest governed run or a specific saved run.

npx martin-loop share --latest
npx martin-loop share --loop-id <loopId>
npx martin-loop share --file ~/.martin/runs/<loopId>/loop-record.json
npx martin-loop share --latest --out-dir ./receipts

By default MartinLoop writes:

  • run-receipt.json
  • run-receipt.md
  • proof-card.svg

The default output location is the selected run directory under share/.

Phase Commands

session-start and phase read local MartinLoop receipts and local phase state, then turn that state into a suggested run contract before work starts.

  • phase status summarizes local posture.
  • phase contract prints the generated contract.
  • phase preflight prints the preflight invocation.
  • phase run prints the governed run invocation.

phase preflight and phase run are dry-run by default. Add --execute only after the generated contract has the right verifier, budget, allowed paths, and blocked paths.