anvil commands
anvil source (mutates)
Section titled “anvil source (mutates)”anvil source [options] [command]
Import and lock API source graphs as immutable content-addressed snapshots.
Layer 0 — capture what the customer actually supplied, before any compilation. anvil source add <dir | file...> imports explicit entrypoint files (plus every local $ref reachable from them) or a whole directory (files declaring openapi:/swagger: become entrypoints; unrelated YAML/JSON is excluded), records each entrypoint’s own format and version, hashes the verbatim bytes deterministically, and atomically locks a snapshot under .anvil/sources/--name attaches a human label that never controls identity or a path, and --origin declares a gateway origin (apigee, mulesoft, kong, api_connect, wso2) independent of the spec format. References escaping the import root are rejected; remote refs are recorded as external, never fetched. Anything readable is snapshotted — broken input locks an invalid (or unclassified) snapshot with its diagnostics inside and exits non-zero, and only valid snapshots may be compiled. list and show are read-only (list reports corrupt slots explicitly); validate <snapshot-id> re-hashes raw/ against the locked source.json, so tampering is caught before it can contaminate a compile.
anvil source add
Section titled “anvil source add”anvil source add [options] <targets...>
Import, discover, freeze, and lock a spec directory or explicit files.
Options:
--name <label>— human label (never controls identity or a path)--origin <kind>— declared gateway origin (apigee, mulesoft, kong, api_connect, wso2)--environment <env>— gateway environment recorded as metadata--gateway-product <product>— gateway product recorded as metadata--organization <org>— owning organization recorded as metadata--workspace <workspace>— gateway workspace recorded as metadata--root <dir>— workspace root for .anvil/sources--json— emit the snapshot, lock directory, and diagnostics as JSON
anvil source list
Section titled “anvil source list”anvil source list [options]
List every locked snapshot, and every corrupt slot.
Options:
--root <dir>— workspace root for .anvil/sources--json— emit the listing as JSON
anvil source show
Section titled “anvil source show”anvil source show [options] <snapshot-id>
Show one locked snapshot in full.
Options:
--root <dir>— workspace root for .anvil/sources--json— emit the snapshot as JSON
anvil source validate
Section titled “anvil source validate”anvil source validate [options] <snapshot-id>
Re-hash raw/ against the locked source.json to detect tampering.
Options:
--root <dir>— workspace root for .anvil/sources--json— emit the verdict and diagnostics as JSON
anvil agentify (mutates)
Section titled “anvil agentify (mutates)”anvil agentify [options] <spec>
One-shot discovery: lock the source, compile, assess readiness, and propose capabilities — then stop for review.
Convenience orchestration of the discovery flow — the same library calls as running anvil source add (locks a content-addressed snapshot under .anvil/sources), anvil compile (writes the bundle, default generated/anvil assess (the readiness triage; blocked operations are surfaced prominently but do not stop the flow), and anvil capability propose (read-only re-discovery over the stored groupings) individually, so the compiled AIR is byte-identical to the four-command path. It then STOPS for human review. It deliberately does NOT approve any capability or operation (every grouping stays proposed, every unproven mutation stays review_required), does NOT certify, and does NOT publish — no certification.json or publication.json is ever written. A broken spec stops at the snapshot layer with structured diagnostics and exit 1; nothing downstream runs.
Options:
--manifest <file>— Anvil manifest with semantic overrides--service <id>— override the derived service id--out <dir>— bundle output directory (default generated/) --root <ws>— workspace root for .anvil/sources--json— emit one machine-readable object with all four stages
anvil compile (mutates)
Section titled “anvil compile (mutates)”anvil compile [options] [spec]
Compile a locked source snapshot into a full tool bundle (CLI + MCP + skill + deploy).
Compiles from an immutable Layer 0 source snapshot: everything the compiler reads — the spec and every local $ref — comes from the locked bytes, and the AIR is bound back to the snapshot’s identity. Pass --source <snapshot-id> to compile an already-locked snapshot (add --entrypoint <path> to disambiguate a multi-entrypoint source), or pass a spec path to import-and-lock it first, then compile that snapshot. Parses OpenAPI/Swagger, classifies effects and idempotency, applies the manifest, validates safety, and writes the bundle. Non-idempotent mutations are escalated to review_required — they are not exposed until approved.
Options:
--source <snapshot-id>— compile an already-locked snapshot instead of a spec file--entrypoint <path>— snapshot-relative entrypoint when a source has several--manifest <file>— Anvil manifest with semantic overrides, workflows, and exact-id capability reviews--service <id>— override the derived service id--out <dir>— bundle output directory (default generated/) --endpoint <url>— MCP endpoint recorded in the generated artifacts--human-approval <policy>— require explicit human approval on gated mutations: none | unsafe | all (per-op manifesthuman_approvaloverrides)--root <ws>— workspace root for .anvil/sources
anvil status
Section titled “anvil status”anvil status [options] <path>
Show source, projection, approval, assurance, target, and release-plan status.
Read-only. Resolves the canonical AIR and locked-source coordinate, verifies generated CLI/MCP/catalog/runtime projections against it, checks static assurance plus current-hash selftest/conformance/simulation evidence, checks deployment-plan freshness, detects stale target setup signatures, and chooses one deterministic next safe action. A local publication.json means only that a plan was prepared; it never means deployed or live. Exit is non-zero only when a core projection is missing, corrupt, or misaligned.
Options:
--root <dir>— workspace root containing .anvil/sources--json— emit one StatusReport JSON document
anvil inspect
Section titled “anvil inspect”anvil inspect [options] <path>
Show the operation catalog and each operation’s safety posture.
Read-only. Use before approving to see effect, risk, idempotency, retry-safety, and state.
Options:
--json— emit the operation catalog as JSON
anvil assess
Section titled “anvil assess”anvil assess [options] <path> [operation...]
Report which operations are agent-ready; gate a pipeline with —check.
Read-only. Runs Anvil’s deterministic detectors and projects every operation’s readiness disposition — ready, refinementRequired, humanDecisionRequired, blocked, or excluded — from the deficiency catalog’s per-code policy plus the lifecycle state, with each gap’s agent impact and an honest remediation (a suggested skill that is not implemented says so). The result is a versioned artifact (schemaVersion, contractHash of the assessed AIR, overallDisposition, readyPercent); --json emits it whole, and --severity narrows the detail into a view without touching the totals. A report that completed exits 0 even with blockers; gating is explicit: --check [--fail-on blocked|human-decision|refinement-required] (default blocked) exits non-zero when the overall or any operation disposition meets the threshold. Drill into one operation with anvil assess <dir> <operation> (or the plan-style ... operation <name>). Reuses the same detectors as anvil refine plan, so the per-operation triage never disagrees with the deficiency list.
Options:
--severity <severity>— narrow the report to a minimum severity--check— gate: exit non-zero at/past the —fail-on threshold--fail-on <disposition>— the disposition threshold —check fails at (default blocked)--json— emit the versioned artifact (or the filtered view) as JSON
anvil distill
Section titled “anvil distill”anvil distill [options] <path>
Strip a surface to its eigenbasis: the minimal spanning set of operations.
Deterministic, read-only whole-surface analysis (a peer of assess). Reads collapse by (resource, action) to one canonical, most-general read per cluster; every write is kept as its own basis vector; same-signature mutations are flagged for review, never auto-dropped. Reports the basis, the reconstructible read projections, the redundant clusters, any intents reachable ONLY through reconstructible ops (which a mechanical strip would lose), and capabilities whose basis still exceeds the tool budget. --json emits the full artifact for the Stage-2 coding-harness loop; --check gates on over-budget capabilities. It proposes only — approval stays an explicit, reviewed step.
Options:
--json— emit the distillation artifact as JSON--check— gate: exit non-zero if a capability’s basis exceeds the tool budget--as-enrich-plan— emit a targeted enrichment plan (the surface’s open questions) instead of the report--write <file>— write the output (report or enrich plan) to a file
anvil capability (mutates)
Section titled “anvil capability (mutates)”anvil capability [options] [command]
Review capability groupings: propose, inspect, approve, reject, or diff.
The capability review lifecycle. propose re-runs discovery and prints each grouping with its provenance and tool-budget verdict (read-only); list and show inspect stored capabilities (small summaries by default; add —operations/—auth/—evidence/—json for detail); diff reports drift between a stored capability and fresh discovery. approve/reject persist the review decision to the AIR file. Approval enforces the effective disclosure budget (direct members plus authored workflow dependencies): more than 20 tools is blocked without —allow-large and an audit note; more than 15 warns. Only an approved capability can be built with anvil build.
anvil capability propose
Section titled “anvil capability propose”anvil capability propose [options] <path>
(Re)run discovery; print proposals with provenance and budget findings.
anvil capability list
Section titled “anvil capability list”anvil capability list [options] <path>
List the stored capabilities and their review lifecycle.
anvil capability show
Section titled “anvil capability show”anvil capability show [options] <path> <capability-id>
Show one capability: small summary by default, sections on request.
Options:
--operations— list the member operations--auth— summarize the members’ auth requirements--evidence— list the evidence claims--json— emit the capability and its budget check as JSON
anvil capability approve
Section titled “anvil capability approve”anvil capability approve [options] <path> <capability-id>
Record the approval decision; the tool budget gates it.
Options:
--allow-large— waive the >20-tool budget block (requires a non-empty —note)--note <note>— review note persisted with the decision
anvil capability reject
Section titled “anvil capability reject”anvil capability reject [options] <path> <capability-id>
Record why the grouping is not the right unit.
Options:
--reason <reason>— rejection reason persisted with the decision
anvil capability diff
Section titled “anvil capability diff”anvil capability diff [options] <path> <capability-id>
Report drift between a stored capability and fresh discovery.
anvil capability compose (mutates)
Section titled “anvil capability compose (mutates)”anvil capability compose [options] <bundles...>
Audit cross-source output overlap and initialize a bound review.
Deterministic and offline. Accepts two or more verified generated bundle directories without modifying them, then writes new audit/review artifacts outside those inputs. It extracts output data-point signatures and reports evidence candidates with auth and safety constraints intersected rather than weakened. Structural similarity never selects an authoritative source. --init-review writes an unresolved manifest; edit it with local digest-bound evidence and rerun using --review. The command never approves, builds, deploys, or generates a multi-source MCP server.
Options:
--out <file>— write the versioned composition audit JSON here--init-review <file>— write a new unresolved review-manifest scaffold; refuses an existing file--review <file>— apply an edited, digest-bound review manifest on a deterministic rerun--json— also emit the complete audit report as JSON on stdout
anvil refine (mutates)
Section titled “anvil refine (mutates)”anvil refine [options] [command]
Detect, propose, measure, and apply refinements to AIR (the quality flywheel).
anvil refine plan runs Anvil’s deterministic detectors and reports a refinement plan — documentation gaps, weak naming/routing, unproven safety semantics, and mock/eval coverage holes — grouped by severity, category, and the narrow skill that owns each fix. anvil refine skills lists those skills as typed contracts (trigger, evidence policy, output boundary, validation), whose executor is kept separate from their semantics. anvil refine run routes each in-scope deficiency to its skill, proposes an evidence-backed semantic patch, validates it, then MEASURES only the eval families it affects — with a safety guard that must never regress — and reconciles the result through an auto-approval policy into a reviewable refinement pack (—severity/—skill/—safe-only/—out). anvil refine review <pack-dir> prints the human review. anvil refine apply applies only the auto-approved refinements to AIR (the sole mutating step; —dry-run to preview), which anvil compile then reprojects across the CLI, MCP, and skill at once.
anvil refine plan
Section titled “anvil refine plan”anvil refine plan [options] <path>
Detect what AIR is missing or weak (read-only).
Options:
--json— emit the refinement plan as JSON
anvil refine skills
Section titled “anvil refine skills”anvil refine skills [options]
List the typed refinement skill contracts (read-only).
Options:
--json— emit the skill contracts as JSON
anvil refine skill
Section titled “anvil refine skill”anvil refine skill [options] [out-dir]
Emit the progressive-disclosure harness skill package.
anvil refine run
Section titled “anvil refine run”anvil refine run [options] <path>
Build a refinement pack: propose, validate, measure, reconcile.
Options:
--severity <severity>— only refine at/above this severity--skill <name>— only run one skill--safe-only— skip refinements that touch safety semantics--out <dir>— write the refinement pack here--json— emit the refinement pack as JSON
anvil refine review
Section titled “anvil refine review”anvil refine review [options] <pack-dir>
Print a refinement pack’s human review.
anvil refine apply
Section titled “anvil refine apply”anvil refine apply [options] <path>
Apply only the auto-approved refinements to AIR (the sole mutating step).
Options:
--severity <severity>— only refine at/above this severity--skill <name>— only run one skill--safe-only— skip refinements that touch safety semantics--dry-run— print the semantic diff without writing AIR
anvil case (mutates)
Section titled “anvil case (mutates)”anvil case [options] [command]
Run a bounded investigation for one deficiency as an isolated case.
The investigation framework. anvil case list <dir> shows the deficiencies a case can be opened for; anvil case open <dir> <target-key> materializes an isolated case workspace (CASE.md + task/target/evidence-policy/allowed-tools/expected-output.schema + workspace/ + output/) that gives a coding agent a case, not a prompt. Inside a case, the agent works only with rails that enforce Anvil semantics — repository search and language tooling are the agent’s own job, not Anvil’s: inspect, add-evidence (enforces the source AND predicate policy), validate-claims (strength + contradictions + predicate policy), synthesize (composes the proposal from gathered claims), validate-proposal (deterministic validation), and finalize (records an honest status — proposal_generated / conflicted / insufficient_evidence / …). anvil case investigate <case> drives the live coding agent; anvil case close <case> <air> re-enters Anvil’s rails — validating and reconciling the proposal into a refinement, bound to the case identity. The agent owns investigation and synthesis; Anvil owns admissibility, safety, validation, and application. AIR is never edited by a case.
anvil case list
Section titled “anvil case list”anvil case list [options] <path>
List the deficiencies a case can be opened for (those with a skill).
Options:
--json— emit the rows as JSON
anvil case open
Section titled “anvil case open”anvil case open [options] <path> <target-key>
Materialize a fresh, immutable case run for one target.
Options:
--out <dir>— case root directory--inspect <fields>— comma-separated AIR fields to pre-inspect--repo-root <dir>— repository root recorded for filesystem evidence--executor <executor>— executor identity recorded in the case
anvil case battery
Section titled “anvil case battery”anvil case battery [options]
Run the investigator benchmark battery.
Run either the deterministic baseline-vs-investigation battery (default, scripted, fast) or, when explicitly enabled, the real-agent investigator effectiveness battery. The default mode is deterministic and does not invoke an external agent.
Options:
--real— invoke a real coding agent for the effectiveness battery--json— emit JSON report--command <command>— agent CLI to drive (default: claude)--model <model>— model passed through to the agent CLI--check— fail on scripted battery expectation mismatches--allow-degraded-native— proceed even when native execution cannot enforce split
anvil case inspect
Section titled “anvil case inspect”anvil case inspect [options] <case-dir>
Print the case’s target inspection.
anvil case add-evidence
Section titled “anvil case add-evidence”anvil case add-evidence [options] <case-dir>
Record one evidence claim (the source and predicate policy gate it).
Options:
--predicate <predicate>— the semantic predicate the claim is about--source <kind>— the evidence source kind--value <value>— the claimed value (JSON when it parses, else a string)--path <file>— file the evidence points at (verified against —lines)--lines <range>— line coordinate for —path, asa-bora--uri <uri>— external coordinate for non-filesystem evidence--ref <ref>— revision/reference the coordinate was read at--note <note>— free-form annotation--confidence <n>— claim confidence in [0,1]
anvil case validate-claims
Section titled “anvil case validate-claims”anvil case validate-claims [options] <case-dir>
Judge the gathered claims: strength, contradictions, predicate policy.
anvil case synthesize
Section titled “anvil case synthesize”anvil case synthesize [options] <case-dir> [pairs...]
Compose the proposal from gathered claims (field=value pairs).
anvil case validate-proposal
Section titled “anvil case validate-proposal”anvil case validate-proposal [options] <case-dir> <path>
Deterministically validate the case’s proposal against AIR.
anvil case investigate
Section titled “anvil case investigate”anvil case investigate [options] <case-dir>
Drive a live coding agent against the case.
Options:
--command <command>— agent CLI to drive (default: claude; codex is protocol-aware)--model <model>— model passed through to the agent CLI--allow-degraded-native— proceed even when native tooling is degraded
anvil case finalize
Section titled “anvil case finalize”anvil case finalize [options] <case-dir>
Record an honest terminal status for the run.
Options:
--status <status>— terminal status to record--summary <summary>— one-line summary recorded with the status--blocked-sources <json>— JSON list of blocked sources, e.g. ’[{“source”:”..”,“reason”:”..”}]’
anvil case delete
Section titled “anvil case delete”anvil case delete [options] <case-dir>
Discard one case run directory.
anvil case close
Section titled “anvil case close”anvil case close [options] <case-dir> <path>
Re-enter Anvil’s rails: reconcile the proposal into a refinement.
Options:
--json— emit the refinement as JSON
anvil enrich
Section titled “anvil enrich”anvil enrich [options] <path>
Connect to published MCP servers (GitHub, Confluence, …) and propose a manifest patch.
Anvil is an MCP client here: it connects to the MCP servers those systems already publish, gathers evidence per operation, and proposes idempotency/confirmation/etc. Propose-only — nothing touches AIR. Loosening safety requires high-reliability (implementation/traffic) evidence; review the patch, then anvil compile --manifest.
Options:
--sources <file>— sources.yaml naming the MCP servers to consult--plan <file>— an enrichment plan fromanvil distill --as-enrich-plan: probe only its targeted operations, routing each question to the matching source pole (code loosens, docs tighten)--write <manifest>— write the proposed manifest here instead of printing it--json— emit the per-operation decisions as JSON--agent <name>— harness agent to use (heuristic|agent-cli; default: heuristic)--agent-command <bin>— CLI command for agent-cli (default: claude)--agent-timeout <ms>— timeout in milliseconds for agent-cli (default: 30000)
anvil estate
Section titled “anvil estate”anvil estate [options] [command]
Assess explicitly tiered gateway inputs and adopt selected APIs.
Run estate support [vendor] first: WSO2 supports native estates, Kong one native declarative state, and Apigee/MuleSoft/API Connect normalized interchange. Reads an adapter-supported offline gateway artifact: a bare document, a ZIP/JAR decoded through the hardened archive harness, or a native WSO2 apictl collection directory. The container reader is not a general native-artifact translator; run estate audit and read the gateway skill reference for each adapter’s exact input boundary. inventory, audit, and plan assess the estate without exposing it; import resolves one exact API/version/revision/environment coordinate into a receipt-bound bundle. Risky operations remain unexposed. Review accepted semantics in a supplemental manifest and re-import; receipt-bound output cannot be approved in place.
anvil estate support
Section titled “anvil estate support”anvil estate support [options] [vendor]
Show the versioned native-vs-normalized gateway support contract.
Reports what artifact shapes Anvil actually accepts, separately from the semantics an adapter models and the fixtures/scale proof behind that claim. Mashery is research-only and is not selectable by inventory/import.
Options:
--json— emit the stable machine-readable support registry
anvil estate connect
Section titled “anvil estate connect”anvil estate connect [options] <export>
Probe the chosen vendor adapter and confirm whether the export is understandable.
Options:
--vendor <vendor>— vendor (kong | apigee | wso2 | mulesoft | api_connect)--entry <path>— archive entry holding the config, when the archive has several--gateway-id <id>— stable gateway control-plane/org/instance id included in the probe digest (default unscoped)--json— emit the connect report as JSON
anvil estate inventory
Section titled “anvil estate inventory”anvil estate inventory [options] <export>
List the APIs in a gateway export without compiling anything.
Options:
--vendor <vendor>— gateway vendor (kong | apigee | wso2 | mulesoft | api_connect)--entry <path>— archive entry holding the config, when the archive has several--gateway-id <id>— stable gateway control-plane/org/instance id included in the inventory digest (default unscoped)--query <text>— filter the view by API id or name (case-insensitive)--owner <owner>— filter the view by exact API owner--lifecycle <state>— filter the view by exact lifecycle state--limit <count>— maximum API rows in the view (default 50)--all— return every matching API instead of applying —limit--summary— emit counts and diagnostics without per-API rows--json— emit the inventory snapshot as JSON
anvil estate audit
Section titled “anvil estate audit”anvil estate audit [options] <export>
Audit a whole gateway estate without compiling or exposing any API.
Builds a deterministic, machine-readable adoption report over the complete inventory: adapter capability gaps, contract fidelity, route ambiguity, authentication evidence, opaque policy findings, accountable owners, and exact next actions. A completed audit exits zero by default even when it finds blockers; use —check to make it a CI gate.
Options:
--vendor <vendor>— gateway vendor (kong | apigee | wso2 | mulesoft | api_connect)--entry <path>— archive entry holding the config, when the archive has several--gateway-id <id>— stable gateway control-plane/org/instance id included in the audit baseline (default unscoped)--json— emit the complete audit report as one JSON document--check— exit non-zero when findings meet —fail-on--fail-on <level>— CI threshold: blocked | review-required (used with —check)
anvil estate plan (mutates)
Section titled “anvil estate plan (mutates)”anvil estate plan [options] <export>
Build a resumable, baseline-aware adoption plan for a gateway estate.
Inventories and audits the complete adapter-supported document, then emits one deterministic adoption-plan artifact for bulk triage while import remains API-by-API. Use —init-selection to create an overwrite-safe coordinate queue whose rows all start in triage; reviewers may mix deterministic_only, agent_assisted, and manual_review per API. The plan captures explicit triage/selected/deferred decisions, accountable owners, dispositions, baseline fingerprints, owner workstreams, stage status, and concrete next actions. Ready rows include an import command template with every reviewed coordinate filled; replace only
Options:
--vendor <vendor>— gateway vendor (kong | apigee | wso2 | mulesoft | api_connect)--entry <path>— archive entry holding the config, when the archive has several--gateway-id <id>— stable gateway control-plane/org/instance id used by every strict import command--selection <path>— versioned YAML/JSON selection file with API decisions, intent, owner, contract, and gateway URL--init-selection <path>— write a new coordinate-aware triage selection file (never auto-selects; refuses existing files)--select <id>— select one exact inventory API id (repeatable; ambiguous revisions/environments require —selection)--baseline <path>— reviewed prior adoption-plan JSON; selections are inherited when no new selection is supplied--out <path>— write the complete deterministic adoption-plan JSON here--check— require —baseline and exit non-zero when source, API, finding, adapter, or selection state changed--json— emit the complete adoption plan as JSON instead of the bounded human view
anvil estate import (mutates)
Section titled “anvil estate import (mutates)”anvil estate import [options] <export>
Import one API from a gateway export and compile it into a bundle.
Options:
--vendor <vendor>— gateway vendor (kong | apigee | wso2 | mulesoft | api_connect)--api <id>— API id fromestate inventory(optional when the estate has one)--gateway-id <id>— stable gateway control-plane/org/instance id when the export does not carry one--strict-identity— require —gateway-id and block unproven required issuer/audience/carrier/principal dimensions--environment <id>— deployment environment; required when the selected API exists in several--api-version <version>— semantic API version; required when a gateway exposes several versions independently of revisions--revision <revision>— gateway revision; required when the selected API has several (for native WSO2: working-copy or revision-N)--entry <path>— archive entry holding the config, when the archive has several--spec <path>— original OpenAPI/Swagger contract; lock it and apply gateway policies instead of compiling route-only synthesis--attest-spec-override <reason>— explicit WSO2 attestation when —spec cannot exactly match one embedded Definitions contract; recorded in the private receipt--manifest <path>— supplemental Anvil manifest, including exact-id capability reviews, applied in the receipt-bound compile--gateway-url <url>— operator-attested public HTTPS gateway base URL; required with —spec so generated tools cannot bypass the gateway--root <dir>— workspace root for the locked source under .anvil/sources--service <id>— reviewed agent-facing service id (default derives from gateway/API/revision/environment)--out <dir>— bundle output directory (default generated// ) --replace-derived— replace verified derived output for the same stable gateway coordinate when approval made it stale or export/inventory evidence changed; verified later lifecycle artifacts are explicitly discarded--json— emit a machine-readable import report (for CI oracles)
anvil estate verify
Section titled “anvil estate verify”anvil estate verify [options] <import-id>
Verify an immutable gateway import receipt and its bound evidence.
Options:
--root <dir>— workspace root for .anvil/imports and .anvil/sources--bundle <dir>— also verify the generated output files against the receipt--json— emit a machine-readable integrity report
anvil sources
Section titled “anvil sources”anvil sources [options] [command]
List enrichment sources, or scaffold a sources.yaml with sources init.
The published MCP servers Anvil enriches from. anvil sources (or sources list) shows the built-in profiles — GitHub, GitLab, Confluence, Jira, Notion, Postman — with the default server for each and whether its evidence can loosen safety (code hosts) or only tighten/corroborate (docs, Postman). anvil sources init <dir> scaffolds a sources.yaml for a compiled service and lists the interview questions to finish it.
anvil sources list
Section titled “anvil sources list”anvil sources list [options]
List the built-in enrichment source profiles.
anvil sources init
Section titled “anvil sources init”anvil sources init [options] <path>
Scaffold a sources.yaml for a service, with the interview questions to finish it.
Reads the compiled AIR and proposes a sources.yaml: the two evidence poles every enrichment wants — a CODE host (the only tier that can loosen safety) and a DOC host (tightens/corroborates, supplies intent phrases) — plus any product vendor it detects (Salesforce, SAP) and a Postman source when the spec came from a collection. It also emits the exact QUESTIONS a coding harness should put to the user (which repo, which space, which env vars) — the interview is agent-native: propose, then refine with the operator. Propose-only; --write <file> saves the scaffold, --json emits the questions + proposal for a harness.
Options:
--write <file>— write the scaffolded sources.yaml here--json— emit the proposal + interview questions as JSON
anvil approve (mutates)
Section titled “anvil approve (mutates)”anvil approve [options] <path> <operation-ids...>
Approve operations so they are exposed by the generated artifacts.
Only approved operations appear in the MCP server, CLI catalog, compiled runtime, and skill. Approve deliberately after inspecting risk. The AIR and every generated projection are staged, checked for exact bytes and surface agreement, then swapped into place together. Receipt-bound gateway imports refuse in-place approval and provide the exact manifest re-import command so import-to-approval lineage stays immutable.
anvil lint
Section titled “anvil lint”anvil lint [options] <path>
Show safety diagnostics; exit non-zero if there are errors.
Surfaces unproven idempotency, missing confirmation, duplicate names, and incoherent retry policy.
anvil build (mutates)
Section titled “anvil build (mutates)”anvil build [options] <path> <capability-id>
Compile one approved capability into an aligned CLI + MCP + skill bundle.
Narrows the AIR document to the capability’s approved operations and reachable schemas, then reuses the whole-service generator, so the capability bundle is the same aligned projection of a smaller model. Refuses (with a structured error) a capability that is missing, not lifecycle-approved, or would build empty. Stamps a content-addressed bundle.json (capabilityHash + contractHash shared by every surface); rebuilding unchanged input reproduces identical hashes.
Options:
--out <dir>— bundle output directory (default generated// ) --endpoint <url>— MCP endpoint recorded in the generated artifacts
anvil review (mutates)
Section titled “anvil review (mutates)”anvil review [options] <dir>
Model-driven semantic review of a bundle’s agent surfaces (MCP/CLI/skill).
Drives a cheap reviewer model (default Haiku via the claude CLI) through Anvil’s artifact-review SOP over a generated bundle: MCP tool descriptions must be truthful to each operation’s effect/risk, the CLI surface must teach confirm/idempotency/dry-run on mutating commands, the skill doc must teach the safety posture and document no phantom operations, and all three surfaces must agree. Every finding must cite verbatim evidence from the bundle; ungrounded findings are discarded mechanically. Native execution is unsandboxed and therefore fails closed unless —allow-degraded-native is supplied; its HOME is isolated and credentials are delivered only through the Claude credential profile. Writes review.report.json into the bundle.
Options:
--model <model>— reviewer model passed to the driver--driver-command <bin>— headless agent CLI to drive--allow-degraded-native— explicitly allow the unsandboxed native reviewer (isolated HOME; host files remain reachable)--json— emit the full review report as JSON
anvil target (mutates)
Section titled “anvil target (mutates)”anvil target [options] <profile> <dir>
Generate an agent-platform connector kit (e.g. Gemini Enterprise) for a bundle.
Validates and generates one explicit Gemini Enterprise registration journey. custom-mcp is console-first; its raw setUpDataConnector files are experimental references. agent-gateway emits guarded Agent Registry, gateway, engine-binding, and rollback artifacts. both is available only when explicitly requested for compatibility. Connector OAuth protects /mcp and is separate from Gemini Enterprise sign-in / Workforce Identity Federation. No files are written when validation fails.
Options:
--surface <surface>— registration surface--server-auth <mode>— MCP resource-server auth mode--endpoint <url>— the connector’s public HTTPS MCP URL (e.g. https://host/mcp)--project <id>— 6-30 character GCP project ID (not the numeric project number)--project-number <number>— provider-assigned numeric GCP project identity used in canonical resources--location <loc>— Gemini Enterprise app/engine location: global, us, eu, or a region--engine <id-or-resource>— GE engine id, or full projects/…/locations/…/collections/…/engines/… resource--gateway-location <region>— Agent Gateway region (required to match the verified app-location matrix)--registry-location <region>— Agent Registry location referenced by the gateway--idp <provider>— connector OAuth provider protecting /mcp; not the GE sign-in IdP--tenant <id>— connector OAuth tenant id / Okta domain--oauth-authorization-url <url>— explicit connector authorization URL (required for —idp other)--oauth-token-url <url>— explicit connector token URL (required for —idp other)--oauth-scope <scope...>— one or more scopes whose resource is this MCP API--inbound-issuer <url>— issuer the MCP resource server validates--inbound-audience <audience>— audience identifying this MCP API--wif <pool>— full locations/global/workforcePools/resource for GE sign-in (separate from /mcp auth) --allow-unauthenticated-mcp— acknowledge that no-auth leaves the public /mcp endpoint without a bearer-token gate--confirm-engine-egress-reroute— acknowledge that Agent Gateway binding reroutes all agent egress for the engine--agent-identity-principal-set <resource>— documented principalSet://agents.global… resource granted registry, gateway, and runtime access--gateway-authorization-policy <resource>— full projects//locations/ /authzPolicies/ resource attached to the gateway --out <dir>— compatibility flag; must resolve to the bundle root because target kits are certified in place--json— emit the plan + compatibility report as JSON
anvil deploy
Section titled “anvil deploy”anvil deploy [options] [command]
Inspect Cloud Run, credentials, and durable idempotency deployment plans.
Plan and inspection only: Anvil prints generated Dockerfile/Terraform/env instructions and verifies the generated durable idempotency-store contract. It does not call Cloud Run, Firestore, apply Terraform, or hold cloud credentials.
anvil deploy cloud-run
Section titled “anvil deploy cloud-run”anvil deploy cloud-run [options] <dir>
The Cloud Run deployment plan (Terraform owns config, Cloud Build the pipeline).
Options:
--env <env>— target environment
anvil deploy credentials
Section titled “anvil deploy credentials”anvil deploy credentials [options] <dir>
The upstream (outbound) credential plan: exact env vars + copy-paste provisioning.
Prints, per auth shape, the exact ANVIL_
Options:
--env <env>— auth profile / target environment--project <id>— GCP project id for links and sm:// references--json— emit one machine-readable credential plan--tfvars— emit only Terraform auto-tfvars JSON for an external plan work directory
anvil deploy ledger
Section titled “anvil deploy ledger”anvil deploy ledger [options] <dir>
Inspect durable-write coverage and the generated Firestore ledger contract.
Read-only and offline. Lists every approved write and its idempotency posture, verifies deploy/idempotency-store.json plus every compiler-owned generated byte against canonical AIR and persisted generator inputs, and prints the selected Firestore database/collection/ANVIL_LEDGER coordinate. Shared mode (default) uses an existing platform-owned trust-domain database; dedicated mode creates one capability-owned database. Static wiring is not live readiness: after applying the reviewed Terraform plan, require the deployed /readyz probe to return 200. Firestore Native is the built-in managed backend; Firebase client SDKs, AlloyDB, and Spanner are not silently substituted.
Options:
--project <id>— resolve {project_id} in the planned ledger URI--database <id>— exact Firestore Native database id, including (default)--database-mode <mode>— shared (existing trust-domain database) or dedicated (create one database)--location <location>— reviewed immutable Firestore location; required only in dedicated mode--ttl-seconds <seconds>— completed replay-result retention (60..31536000; defaults from the generated contract)--json— emit one machine-readable offline readiness report--tfvars— emit only Terraform input JSON (requires —project and —database; dedicated also requires —location)
anvil certify (mutates)
Section titled “anvil certify (mutates)”anvil certify [options] <path>
Run static bundle-assurance gates and write certification.json.
Static assurance only: four deterministic gates judge the bundle as emitted. CONTRACT re-validates AIR, generated-surface alignment, and persisted target-kit regeneration; SAFETY checks confirmation, retry/idempotency, and secret handling; SEMANTIC checks descriptions and routing; RUNTIME checks generated mocks, evals, conformance tests, and deploy artifacts. The record binds to a content hash, so generated-byte tampering invalidates it. It does not boot or invoke a surface; use anvil selftest, anvil conformance, and anvil simulate for executable evidence.
Options:
--json— emit the full certification as JSON
anvil selftest (mutates)
Section titled “anvil selftest (mutates)”anvil selftest [options] <dir>
Boot the bundle’s mock + MCP servers and prove the generated surface end-to-end.
Loopback self-test for bundles with no reference server to compare against: starts the generated mock upstream (mock/server.mjs) and the generated MCP server (mcp/server.js) pointed at it via ANVIL_BASE_URL, then invokes every approved tool over the real MCP transport. Checks: the tool surface equals the approved operations (surface), every argument reaches the wire faithfully and the response round-trips (fidelity), confirmation gates refuse before any side effect (confirmation-gate), documented upstream errors surface as structured envelopes (error-mapping), and non-idempotent mutations are never auto-retried (retry checks). Writes selftest.report.json into the bundle. Exit 0 only when no check fails.
Options:
--json— emit the full report as JSON
anvil conformance (mutates)
Section titled “anvil conformance (mutates)”anvil conformance [options] <dir>
Prove the CLI, MCP, and skill surfaces agree on every operation, end-to-end.
Tri-surface conformance for a generated bundle. Boots the bundle’s mock upstream, then drives every approved operation through BOTH the generated MCP server (mcp/server.js, over the real MCP transport) and the generated CLI entrypoint (cli/
With —live <config.json>, probes a REAL deployed MCP endpoint instead of the mock. Before any tool call, the endpoint must attest the exact SHA-256 of the local deploy/runtime artifact. It then verifies the certified surface and production confirmation gate, and invokes only reads explicitly opted into by the operator — never a real mutation. For delegated/OBO identity, at least one successful read is required for every distinct identity and credential contract group; a write-only group remains unverified and the separate identity-live gate fails. /readyz, OIDC discovery, JWKS reachability, and matching tool names alone never prove readiness. The config names the endpoint (mcpUrl) and auth headers, whose ${VAR} values resolve from the environment; the onus of correct config is on the operator. Writes conformance.live.report.json.
Options:
--live <config>— probe a real deployed MCP endpoint named in this JSON config--json— emit the full report as JSON
anvil benchmark
Section titled “anvil benchmark”anvil benchmark [options] <dir>
Measure agent-task completion probability: tool discovery, param satisfiability, call success, pagination.
Deterministic benchmark for each approved operation’s agent-task potential. Derives one task per skill.intentExamples entry; scores each on tool discoverability in the MCP server, required-param satisfiability from synthesized examples, call success against the mock upstream, and (for paginated operations) cursor-param pagination. Writes benchmark.report.json with per-operation task results, pass/fail counts, and an aggregate score. Exit 0 only when aggregate score meets the threshold.
Options:
--check <threshold>— exit non-zero if score < threshold (0..1)
anvil simulate (mutates)
Section titled “anvil simulate (mutates)”anvil simulate [options] <dir>
Drive the full safety matrix through the simulator and report coverage.
Mechanistic coverage for a bundle’s approved surface. Enumerates the matrix (each operation × the safety dimensions that apply: auth scope gating, confirmation refusal, required-idempotency + replay, injected faults, pagination) and drives every cell through the deterministic simulator, checking each against an independent contract expectation. Then runs the mutation battery — deliberately weakening each safety control and proving the surface signature detects it. Reports per-dimension coverage and mutants killed. Deterministic: same seed + contract → same cells. Writes simulation.report.json. Exit 0 only when every cell holds and every applicable safety mutant is killed.
Options:
--seed <n>— deterministic simulator seed--json— emit the full report as JSON
anvil publish (mutates)
Section titled “anvil publish (mutates)”anvil publish [options] <dir>
Prepare a gated deployment plan; make no cloud API calls.
Compatibility note: publish prepares a deployment plan; it does not publish, apply, deploy, or contact a cloud API. Fresh static assurance and fresh passing selftest, conformance, and simulation reports must all match the current bundle content. On success it prints the Cloud Run operator plan and writes publication.json with the evidence snapshot. --allow-uncertified and --allow-incomplete-evidence are explicit non-prod-only waivers; prod always fails closed. Cloud Run is the sole target and therefore the default.
Options:
--target <target>— publish target--env <env>— target environment (default from ANVIL_ENV, else dev)--allow-uncertified— waive static assurance for this plan (non-prod only)--allow-incomplete-evidence— waive missing, stale, corrupt, or failing executable evidence (non-prod only)--json— emit the publication record as JSON
anvil sync (mutates)
Section titled “anvil sync (mutates)”anvil sync [options] <spec-path> <path>
Detect semantic drift between the current spec and a stored AIR contract.
Layer 6 — drift and recertification. Re-imports the spec through the Layer 0 snapshot layer (unchanged content is a fast path: same sourceHash, no drift), recompiles it in memory, and diffs the fresh contract against the stored AIR: operations added/removed, field type and requiredness changes, auth scope/type changes, retry/idempotency/confirmation semantics, pagination, and documentation-only edits (info). Safety-loosening drift (a dropped confirmation, new retries, an idempotency claim crossing “none”, auth vanishing) is blocking; other safety-semantic drift is high. Reports which capabilities are affected and which certifications must be re-earned even though their bundle bytes are untouched, then writes a drift record to .anvil/drift/
Options:
--manifest <file>— Anvil manifest applied to the in-memory recompile--root <ws>— workspace root for .anvil/sources and .anvil/drift--json— emit the drift verdict (and record) as JSON
anvil drift (mutates)
Section titled “anvil drift (mutates)”anvil drift [options] [command]
List, inspect, and mark reviewed the drift records anvil sync stored.
list shows every stored drift record with its severity mix and review status; show <id> prints one record in full (items grouped by severity, affected capabilities, invalidated certifications). accept <id> [--note ..] stamps reviewedAt on the record — bookkeeping only: accepting drift never edits AIR, never restores a certification, and never changes capability lifecycles. Act on drift deliberately with anvil compile, anvil certify, and the capability review commands.
anvil drift list
Section titled “anvil drift list”anvil drift list [options]
Every stored drift record as a small table.
Options:
--root <ws>— workspace root for .anvil/drift--json— emit the records as JSON
anvil drift show
Section titled “anvil drift show”anvil drift show [options] <id>
One drift record in full.
Options:
--root <ws>— workspace root for .anvil/drift--json— emit the record as JSON
anvil drift accept
Section titled “anvil drift accept”anvil drift accept [options] <id>
Stamp the record reviewed (bookkeeping only).
Options:
--note <note>— review note stored on the record--root <ws>— workspace root for .anvil/drift--json— emit the reviewed record as JSON
anvil run (mutates)
Section titled “anvil run (mutates)”anvil run [dir] [args...]
Invoke an operation through the safety runtime.
Supports —dry-run, —confirm, —idempotency-key, —schema, —examples, —errors, —policy, —explain, —json, —trace. Route through MCP with —mcp stdio, —mcp
anvil serve
Section titled “anvil serve”anvil serve [options] [command]
Serve the generated MCP server over stdio.
Boots the MCP server for local agent use. The same server deploys to Cloud Run for remote use.
anvil serve mcp
Section titled “anvil serve mcp”anvil serve mcp [options] <dir>
Serve the bundle’s MCP server on stdio.
anvil package (mutates)
Section titled “anvil package (mutates)”anvil package [options] [command]
Validate and package the portable skill package.
The skill is also served over MCP as anvil://skill/
anvil package skill
Section titled “anvil package skill”anvil package skill [options] <dir>
Validate the bundle’s skill package against the Agent Skills spec.
Checks SKILL.md frontmatter (spec-legal name and description), that every path SKILL.md references exists, that every markdown file self-describes with frontmatter, that examples parse and cover their schema’s required fields, and that no absolute paths leak. With —out, copies the skill to
Options:
--out <dir>— copy the validated skill to/ /
anvil skill
Section titled “anvil skill”anvil skill [options] [out-dir]
Emit the skill that lets an agent harness operate anvil.
Generates SKILL.md plus reference/ and evals/ for operating the anvil CLI itself. The command reference is derived by walking anvil’s own Commander tree — the same tree that parses this invocation — so the skill never drifts from the CLI.