CLI reference

REFERENCE · GENERATED FROM THE COMMAND REGISTRY

Every command below comes from the same registry that drives routing, maverick help and the Lens CLI explorer, so this page cannot drift from the binary. Search, filter by group, and click a usage line to copy it.

⌕65

maverick lensdashboarddashGet started

Open Maverick Lens, the local project-intelligence view.

maverick initGet started

Interview the project, then set up Maverick and the flow skills for every AI agent (shared in .agents/, linked into each tool).

maverick languagelangGet started

Show or set the language of the flow documents and of the code.

maverick newstartopenPlan & build

Start the flow in your AI agent: from an idea (or a task slug to resume) to PRD, behavioral spec (spec-driven), technical spec, tasks, build, review and ship.

maverick instructionsPlan & build

The idea, current stage, required headings, grounding and findings for a stage skill.

maverick generatePlan & build

Run the planning stage skills headlessly with a trusted, read-only agent.

maverick subtaskPlan & build

Break a task into a dependency graph of subtasks.

maverick flowFlows & agents

Run contract-driven flows with typed gates, iteration caps, and stall detection.

maverick loopFlows & agents

Run an agent loop the harness decides: checkpoints, rollback, integrity guard, budgets, escalation and a verifiable ledger.

maverick arenaFlows & agents

Run one subtask with several providers at once; the winner comes from evidence (oracle, holdout, integrity, ablation, architecture, diff, an independent judge) and a human confirms it.

maverick agentFlows & agents

Run trusted AI coding agents headlessly with scoped permissions.

maverick mapProject intelligence

Build a repository context map.

maverick stackProject intelligence

Detect languages, frameworks, and verification commands.

maverick graphProject intelligence

Analyze the import graph: cycles, hubs, coupling, and health; --trend shows health over time.

maverick hotspotsProject intelligence

Rank files by change frequency and dependents.

maverick routesendpointsProject intelligence

List entry points in any stack: HTTP routes, pages, GraphQL, gRPC, events and jobs.

maverick couplingarchitectureProject intelligence

Component coupling: Ca, Ce, instability, abstractness, distance, cycles and boundary rules.

maverick auditfindingsProject intelligence

Architecture findings with evidence: cycles, hubs, hotspots, hidden coupling, route and contract issues.

maverick mcpFlows & agents

Serve read-only project intelligence to AI agents over MCP (stdio).

maverick packetrunPlan & build

Compile a focused agent packet.

maverick checkpointVerify & review

Save current Git state and diff.

maverick impactProject intelligence

Find bounded project references to a file.

maverick guardVerify & review

Compare changed files with declared task scope.

maverick integrityVerify & review

Catch weakened checks: deleted or skipped tests, looser assertions, silenced lint, edited check config.

maverick ablationVerify & review

Check that new tests can fail: each must pass with the change and fail without it.

maverick structureVerify & review

Ratchet the import structure: no new cycle, no new boundary violation, no health drop (the architecture gate).

maverick sealVerify & review

Seal, review and amend acceptance tests kept from the builder.

maverick unsealVerify & review

Open a task's sealed tests at review: commit them as protected regression tests, or discard them.

maverick contractcontractsVerify & review

Living contracts left by finished tasks: list, show, harvest, check a change, revoke or review.

maverick attentionreview-budgetVerify & review

The review budget: hunks ranked by risk, a time range, and a proof tree per criterion.

maverick explainVerify & review

Explain-back (experimental): a read-only agent asks the reviewer three questions about what the change does; answers go to REVIEW.md. Opt-in, never blocks.

maverick proofVerify & review

Sign and verify the proof receipt: what proved a change (intent, ledgers, gates, holdout, verdicts, approvals, models) as a signed in-toto attestation.

maverick scorecardDecide with evidence

Aggregate repository evidence with confidence intervals and integrity penalties.

maverick routeDecide with evidence

Propose reviewed runtime routes from repository evidence.

maverick autonomyDecide with evidence

Propose autonomy from clean, mature post-merge evidence.

maverick canaryDecide with evidence

Measure provider integrity in an isolated contradictory task.

maverick decisionDecide with evidence

Install versioned rubrics, label decisions and inspect calibration.

maverick trifectaDecide with evidence

Report private data, web and external-write exposure for this session.

maverick whyProject intelligence

Why a line exists: its task, criterion, loop iteration, evidence, decisions and guarding contracts.

maverick groundingProject intelligence

Grounding precision: the files maverick new suggested versus the files each task really changed.

maverick proposalsproposalDeliver

Rules learned from loop failures: harvest, accept or reject, and measure whether accepted rules work.

maverick learnDeliver

Capture a proposed reusable engineering rule.

maverick handoffDeliver

Create a task handoff with remaining gates.

maverick readinessVerify & review

Evaluate merge-readiness gates.

maverick policyVerify & review

Initialize, show, or check repository policy.

maverick adapterFlows & agents

List or install an AI adapter.

maverick ciDeliver

Generate a GitHub Actions task gate.

maverick catalogCapabilities

Browse, search, show, or validate available capabilities.

maverick addCapabilities

Install skills, agents, commands, or MCP servers into AI tools.

maverick removeCapabilities

Uninstall capabilities and their managed files.

maverick installedCapabilities

List installed capabilities, drift, and updates.

maverick syncCapabilities

Update installed skills and capabilities to the catalog, restore drifted files, or bring a task to the current format.

maverick verifyVerify & review

Run detected checks for any stack and save evidence.

maverick securityVerify & review

Scan a changed diff for high-signal security risks.

maverick depsVerify & review

Report changed manifests and lockfiles.

maverick prDeliver

Write the evidence-backed PR draft, or open the pull request on the repository's provider (GitHub, GitLab, Azure DevOps, Bitbucket).

maverick donefinishDeliver

Finish a task once its pull request has landed (--force before the PR stage); its invariants become living contracts.

maverick reopenDeliver

Reopen a finished task.

maverick validatePlan & build

Validate the PRD, behavioral spec (spec-driven), technical spec and tasks up to the task's current stage (--all for every stage): headings, criteria ids, scenarios, real paths and coverage.

maverick reviewVerify & review

Show review or review a diff.

maverick configConfiguration

Show, validate, or locate layered configuration.

maverick doctorGet started

Inspect local setup, toolchains, and project checks.

maverick statusGet started

Show task stage and pending gates.

maverick infoversionConfiguration

Show Maverick information.

maverick helpConfiguration

Show usage, or details for one command.

Details for one command

maverick help <command> prints usage, aliases, group and related commands. Most operational commands accept --json for automation.

Command details

Tasks and delivery

maverick init interviews you, then writes .maverick/config.json. In a terminal it is a step-by-step wizard (↑↓ to move, space to toggle, a for all, enter to confirm, esc to go back or cancel) that asks the project name, what the project does and for whom, which AI agents work on it as a checkbox list (Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Kiro, OpenCode; the ones found in the repository or on the machine come pre-checked), the docs language (default from LANG, so pt_BR.UTF-8 gives pt-BR), the code language (default en), the default workflow and which detected verification commands to use, then shows a summary before writing anything. Every question has a flag for scripts: --name, --description, --agents claude,kiro,codex, --docs-language, --code-language, --workflow standard|strict, --verify "npm test; npm run lint"; --yes accepts the suggestions. It installs the eight flow skills once into .agents/skills/ and makes each chosen tool's skills folder a symlink to it (.claude/skills → ../.agents/skills), writes AGENTS.md from the answers when it is missing, and links CLAUDE.md and GEMINI.md to it for the tools that do not read AGENTS.md. Existing files are never replaced. --no-skills and --no-instructions skip those steps. On an initialized project, maverick init --agents gemini adds agents without asking again. maverick language (alias lang) shows the languages; maverick language pt-BR en sets docs and code, --docs <code> or --code <code> sets one, and --json prints them. maverick new "<idea>" (aliases open, start) derives a slug from the idea (--slug to choose), writes TASK.json, grounds the idea in the code (ranked relevant files with reasons, nearby tests, entry points, shared modules, verification commands) and, in a terminal, opens your AI coding agent with the eight flow skills installed, prompted with the skill for the task's stage (--agent to choose; --strict for the strict workflow; --no-launch to only create the task). maverick new <slug> resumes a task in the agent with the skill for its stage: planning uses maverick-new, build maverick-build, verify, security and review maverick-review, and PR maverick-ship. maverick new with no idea opens the agent, which asks what to build. Without a terminal it only creates the task. maverick instructions <task> [prd|techspec|tasks] [--json] returns what a skill needs: the idea, current stage, required headings, earlier artifacts, grounding and findings, plus skill, language (docs, code, rule, keywords) and tasks (total, done, ready with paths, in progress). maverick generate <task> [stage] --agent <provider> [--answers "…"] runs the stage skills headlessly with a trusted, read-only agent, then writes and strictly validates each artifact, retrying once with the failures. validate <task> [--stage prd|techspec|tasks] [--strict] checks headings, unique acceptance-criteria ids, requirement scenarios, that referenced paths exist, that the Test Plan covers every criterion, and that every criterion is covered by a task. status shows each task's stage and names the skill for its next step. map, packet, run, verify, checkpoint, impact, guard, security, deps, review --diff, pr, handoff, readiness and done turn those artifacts into an auditable delivery workflow. See From idea to tasks.

Repository configuration

policy init|show|check, adapter list|install, and ci github <task> provide repository-level configuration, agent instructions, and an optional GitHub Actions task gate. Most operational commands accept --json for automation.

Stack and configuration

stack [--json] reports detected languages, frameworks, package managers, task runners, subprojects, and the exact commands verify will run for JavaScript/TypeScript, Python, Go, Rust, Java/Kotlin, .NET, Ruby, PHP, Elixir, Dart/Flutter, and Swift projects. config show|validate|path inspects the layered configuration (defaults, ~/.maverick/config.json, project). doctor also checks that each detected toolchain binary is installed. help is generated from the same command registry used for routing and the Lens CLI explorer.

Capabilities

catalog [search <text>|show <name>|validate], add <capability...> [--to <tools>] [--dry-run] [--yes] [--force] [--allow-exec], remove <capability...>, installed, and sync manage skills, agents, commands, and MCP servers across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Kiro, and OpenCode. With capabilities.layout: "linked" (the default, except on Windows) each capability is written once to .agents/ and each tool's skills folder is a symlink to .agents/skills (.claude/skills → ../.agents/skills), so every skill, including ones you add, is shared by all agents; skills already in a tool's folder are moved into .agents/skills first, and a name that differs between tools stops the install; maverick sync installs the new catalog version of every capability that changed (shown as UPDATE lines and applied only with --yes or a confirmation; --no-update only restores drifted files), adds flow skills that are new in a release wherever maverick-new is installed, and converts an existing install when the layout changes; maverick sync <task> converts a task written by an older Maverick to the current format (checklists for criteria, steps and tests, and _tasks.md as a checklist of the tasks), with --dry-run to preview; agents, commands and MCP servers whose format differs per tool are rendered for each one. "copy" writes each tool its own files. Installs are planned before anything is written, recorded in .maverick/capabilities.lock.json with content hashes, and never overwrite files or JSON keys Maverick does not own unless --force is passed.

Flows and subtasks

flow list|show|validate|run <flow> <task> [--reset] [--auto-approve]|status <task>|approve <flow> <task> <gate>|auto-approve [<flow> on|off] runs contract-driven flows: typed gates (check, maverick, command, artifact, approval, and judge, an independent agent from another model family that decides the criteria and waits for flow approve when the judges disagree), an iteration cap, and a no-progress window, ending in done, revise, awaiting-approval, stalled, or exhausted (only done exits zero). flow approve (--reject --reason "..." to request changes) checks the matching box in the gate's file, such as - [x] approve in REVIEW.md, and decides a run that was only waiting on it right away. --auto-approve runs without waiting for a human: once every blocking check passes, pending approval gates are approved and marked as auto-approved; flow auto-approve <flow> on makes that the default for a flow in .maverick/config.json. subtask add|list|next|set|validate <task> manages an acyclic subtask graph whose dependencies are enforced when work starts or finishes.

Pull requests and finishing a task

pr <task> writes PR-DRAFT.md from the evidence: its heading is the pull request's title and the rest its description, so you can edit both (--keep keeps a draft that already exists). pr open <task> opens the pull request on the provider the origin remote names: GitHub with gh, GitLab with glab, Azure DevOps with az repos, or Bitbucket (pr.provider when the host does not say). On the base branch the change moves to maverick/<task> first, uncommitted changes outside .maverick/ are committed with the title through your hooks, and the branch is pushed, never forced. A pull request already open for the branch is reused. Without the provider's CLI the branch is still pushed and the provider's new-pull-request page is printed. The result is recorded as pullRequest in TASK.json.

The built-in pr flow (flow run pr <task>) runs the whole step: it checks the review decision and merge readiness, keeps or writes the draft, waits for the approval gate (Lens, flow approve pr <task> approval, or the checked box in PR-DRAFT.md), then opens the pull request. Its open gate never runs before every blocking gate before it passed, so nothing is pushed before the approval. --auto-approve, or flow auto-approve pr on, approves the draft once the other gates pass.

done <task> [--by <name>] [--note <text>] [--no-contracts] (alias finish) finishes a task once its pull request has landed: TASK.json records who and when, the stage becomes done, and the task's SPEC invariants and the criteria its committed sealed tests prove become living contracts. Before the PR stage it takes --force. reopen <task> undoes it.

Loops

loop run|status|stop|verify|log|release|clean <task> runs a loop the harness decides: one subtask per iteration with a fresh agent context (or the flow's goal when the task has no subtasks), an integrity audit of each diff, the oracle gates (--flow, default the built-in loop flow), and a ratchet that keeps each iteration as a checkpoint or rolls it back. loop run takes --max-iterations, --max-minutes, --max-cost and --max-tokens (hard limits, with a forecast that stops before an iteration that would cross one), --worktree (its own git worktree and branch maverick/loop/<task>, with loop.setup run once), --judge (a reviewer from another model family must accept each subtask and the whole change), --feedback detailed|criteria|generic (what the next agent learns from a rejection; criteria by default), --sealed auto|required|off (whether the task's sealed tests decide done), --provider, --model, --effort, --permission, --dry-run (the plan and first prompt, writing nothing), --resume --note "..." (continue after a human decision) and --new. Only done exits zero; stalled-escalated, disputed, needs-human, holdout-gap and integrity-violation write LOOP-ESCALATION.md. A resumed loop records what changed since it stopped (configuration, flow, oracle files you edited, the seal) as drift in its ledger. loop stop aborts the running agent and rolls its changes back (--after-iteration lets it finish), loop verify checks the hash-chained ledger against every checkpoint ref, loop log prints the ledger, loop release releases the notes a loop quarantined (notes from an iteration with integrity findings never reach the next agent on their own) and acknowledges the checkpoint's taint, and loop clean removes the checkpoint refs and the worktree (--delete-branch also deletes the branch) while keeping the ledger. integrity <task> [--against <ref>] [--level strict|standard|off] [--oracle] runs the same integrity audit on any change and writes INTEGRITY.md.

The proof layer

loop graph <task> [--plan] [--max-lanes n] runs a task's subtasks in parallel lanes where the code allows it, merges them at a fan-in and checks the merged work; --plan shows the predicted collisions and lanes. loop run <task> --lane <id> --only 01,02 [--start-point <ref>] runs one lane. loop replay <task> [--loop <id>] --set <key>=<value> replays a recorded loop through the policy functions under other settings; loop fork <task> --from <iteration> --provider <id> starts a new loop from a recorded checkpoint in a worktree of its own. arena run <task> --subtask <id> --providers a,b[,c] builds one subtask with several providers at once and ranks them by evidence; arena confirm <task> <id> applies the winner a human confirms; arena status|list|verify|stats. proof keygen|sign|verify|show|export signs and verifies the proof receipt and exports it as Agent Trace or an AI-BOM. explain <task> [--force] [--answer Q1 --text "..."] asks the reviewer three questions about the change (with review.explainBack). grounding [<task>] measures how many of the files grounding suggested the task really changed. See The proof layer.

Checks of the checks

ablation <task> [--against <ref>] [--level strict|standard|off] runs each new or changed test file twice in exports outside the repository: with the change, where it must pass, and on the code before it with only the new tests on top, where it must fail. A test that passes both ways is vacuous-test (a warning, blocking at strict); a test the TECHSPEC Test Plan marks as a regression guard is expected to pass both ways. It writes ABLATION.md and is the ablation gate (in the ship flow, as a warning). structure <task> [--against <ref>] compares the import graph before and after the change: a new cycle, a new import that architecture.rules forbids, or a health drop beyond architecture.maxHealthDrop fails it, unless the TECHSPEC declares the edge under ## Architecture. It writes ARCHITECTURE-CHECK.md and is the architecture gate, blocking in the built-in loop flow so no iteration can make the structure worse.

Sealed tests

seal <task> has an independent agent, from a model family no builder of the task belongs to, write acceptance tests from the PRD's criteria and the SPEC's scenarios, read-only in an export of the code; --provider, --model, --effort choose it, --surface spec|techspec|boundary says what the tests may call, --from-file <dir|bundle.json> seals a suite you wrote (kept outside the project), and --dry-run prints the sealer and its prompt. Each test must fail on the code as it is. The suite is encrypted outside the work tree; the task keeps only SEALED.json (digests and counts). seal approve <task> records your approval. seal status <task> shows the seal, its approval and staleness; --reveal, only at an interactive terminal, shows each test, its last result and the escape set. unseal <task> --commit [--protect] writes the tests into the project for you to commit (--protect adds them to loop.protectedPaths); unseal <task> --discard deletes them from the vault. Both are recorded in REVIEW.md, and merge readiness waits for one of them. In a flow, { id: holdout, type: sealed } runs the suite against the working tree.

Memory

why <file:line> (or <file>#L<n>) shows the chain behind one line: the commit, the Maverick task, the criteria its subtask serves, the loop iteration that wrote it (agent, model, effort, decision), the gates and integrity audit of that iteration, the judges, the sealed suite, the flows' approvals, the human review, and the contracts and protected paths that guard it now; what is missing is listed. why <task> --ac <AC-01> walks back from a criterion to its subtasks, files, iterations, judges, committed sealed tests and contracts. Both take --json; the MCP server has a why tool.

contract list [--all], contract show <id>, contract harvest <task>, contract check [<task>] [--against <ref>] [--strict] [--no-run], contract revoke <id> --reason <why> and contract review <id> manage living contracts in .maverick/contracts/. done harvests a task's SPEC invariants and the criteria its committed sealed tests prove (--no-contracts skips it). check runs the tests of every active contract the change touches; with a task, its PRD may revoke a contract (Revokes C-07: <why>); without one, a touched anchor is reported as drift (--strict fails on untested drift). It is the contracts gate.

proposals [list] [--all], proposals harvest [<task>], proposals accept <id> [--text <rule>] [--paths <glob,…>] [--agents-md], proposals reject <id> --reason <why> and proposals stats run the error ratchet: loop rollbacks, judge rejections, escalations and disputes become one proposal per failure class in .maverick/proposals/, harvested at the end of every loop run. Accepted rules reach an agent's prompt only when its subtask touches their paths; --agents-md keeps a managed block in AGENTS.md; stats compares each class's occurrences per loop before and after the rule.

attention <task> [--against <ref>] writes REVIEW-BUDGET.md: hunks ranked by risk (blast radius, hotspot, integrity warning, judge uncertainty or rejection, sealed escape set after unsealing, no nearby test changed), a review time range and a proof tree per criterion. It is the review-budget gate, and pr adds its summary to PR-DRAFT.md.

graph --trend [--json] shows architecture health over the snapshots each graph, coupling and audit run records in .maverick/cache/graph/.

Headless agents

agent list|trust <provider>|untrust <provider>|run <task>|runs <task> runs Claude Code, Codex, Cursor CLI, Gemini CLI, or custom CLIs headlessly. agent run accepts --subtask <id|next>, --prompt, --provider, --model, --permission read-only|edit|full, --timeout <minutes>, and --dry-run; permissions never exceed runtime.maxPermission, and only providers in runtime.trusted run. flow run <flow> <task> --agent [provider] lets the agent fix blocking issues between runs until the flow is done, stalled, exhausted, or the agent asks for a human. Each fix has the guarantees of a loop iteration: the task and check configuration are put back if the agent changes them, a commit or checkout by the agent stops the flow, and a fix whose own diff weakens a check is rolled back. The agent reads the issues as loop.feedback allows. agent run reports tokens and the cost, estimated from runtime.prices when the provider reports tokens only.

Project intelligence

graph [--json] [--format mermaid|dot] [--depth <n>] reports the resolved import graph across languages (cycles, hubs, fan-in, instability, and a health score with its formula). impact <path> lists transitive dependents and the tests to run, falling back to text references for non-source files. hotspots [--since <git date>] [--limit <n>] ranks files by churn and dependents. mcp starts a read-only Model Context Protocol server over stdio; its ground_change tool returns the same grounding as maverick new.

routes [--kind http|page|graphql|rpc|event|job|websocket] [--method <verb>] [--grep <text>] [--json] lists entry points in any stack—decorators and annotations, router calls, file-system routing and OpenAPI, GraphQL or protobuf contracts—with guards, duplicates, contract drift and write routes without a guard. coupling [--json] reports components with afferent and efferent coupling, instability, abstractness and distance from the main sequence, component cycles, Stable Dependencies Principle violations and configured boundary rules. audit [--severity high|medium|low] [--category <name>] [--fail-on high|medium|low] [--json] ranks every architecture finding with its evidence; --fail-on makes it a CI gate. impact <path> also lists the entry points served by the affected files. See the Devtools guide.

Decide with evidence

maverick scorecard --json
maverick route suggest
maverick autonomy suggest
maverick canary run --provider codex --dry-run
maverick canary run --all
maverick decision init
maverick decision calibration integrity
maverick decision label integrity <id> --answer refactor --by reviewer --reason "Assertions preserved"
maverick trifecta --json

Routes and autonomy are written to .maverick/policy-proposals/*.patch, never applied automatically. Decide describes samples, calibration and safety signals.

maverick seal review <task>
maverick seal amend <task> --from-file <bundle.json> --reason "Corrected disputed behavior"
maverick seal suspend <task> ST-01 --reason "Contradicts the approved contract"
maverick seal restore <task> ST-01 --reason "Dispute resolved"

Amendment and suspension revoke approval. The suite stays encrypted outside the repository. See Sealed tests.