Two first-class ways to work
The CLI supports direct operation and scripted automation. MCP exposes the same admitted capabilities for structured client and agent orchestration. Agent-assisted MCP can reduce command-level effort by handling tool selection, argument preparation, and result chaining, while permissions, verification requirements, and human approvals remain enforced.
This does not mean every CLI workflow is already admitted through MCP, or that every legacy CLI command uses the strict service path. Consult the current catalogue and the complete CLI reference. Neither interface turns model agreement or a successful tool call into proof.
| Use case | Recommended approach |
|---|---|
| Investigating an unfamiliar component or coordinating several tools | Agent-assisted MCP, with explicit scope and approvals |
| Repeating known checks on every pull request or release | Scripted CLI/CI, with fixed acceptance rules |
| Debugging a specific invocation or reproducing a failure | Direct CLI |
| Sensitive promotion or signing | Either interface through the authenticated approval workflow where implemented; otherwise an explicitly authorized human-operated path. See current approval support. |
Direct CLI and scripted automation
Choose commands and arguments yourself, inspect diagnostics, and repeat approved checks without a model.
Start a manual workflow · All CLI commands and optionsStructured MCP orchestration
Use a client or agent to prepare calls and chain admitted results. The server still resolves effects, enforces scope, and preserves approval boundaries.
Explore admitted tools · Understand the bounded supervisorDirect CLI and CI workflows
Run these examples from your application workspace using a trusted, provisioned FormalSpecGen installation. Source and domain files are inputs you supply; examples are not pre-certified results. Use a fresh output namespace for each run and never delete prior evidence just to make a retry succeed.
Built-in commands with --json accept --json - for one formalspecgen-cli-result-v1 response on stdout, with diagnostics on stderr. Read the actual payload under result; operation_satisfied is not a proof claim. Early dispatch failures can return a null result and an error; argument-parser errors retain stderr/exit-2 behavior. --json PATH preserves the existing payload format and never replaces an existing result file. Other requested workflow artifacts are still produced. Signed refactoring requires a file destination.
formalspecgen inspect src/Counter.java --json -
Investigate and document
formalspecgen inspect src/Counter.java --json results/run-001/inspection.json
formalspecgen analyze-codebase src --out-dir analysis/run-001 --project-root models/run-001 --json results/run-001/analysis.json
formalspecgen document-code src/Counter.java --out docs/run-001/counter.md --project-root models/docs-run-001 --no-llm --json results/run-001/documentation.json
These produce findings and unreviewed proposals, not proof. --no-llm makes documentation provider-free. The equivalent MCP examples below use the configured MCP output root; CLI destinations follow the local command's output policy.
Check a candidate and its baseline
formalspecgen verify src/Counter.java --mode esc --json results/run-001/verification.json
formalspecgen verify-refactor baseline/Counter.java candidate/Counter.java --json results/run-001/preservation.json
For CI, prepare fresh output directories, pin the input revision and toolchain, and fail on unsuccessful commands. Also inspect the structured outcome, claim, bounds, source identity, and required receipts against fixed acceptance rules. Parsing or static checking is not a substitute for an ESC objective; preservation is not general behavioral equivalence.
Trace requirements without inferring proof
formalspecgen generate-traceability-matrix domain.yaml src --reqs requirements.req --out reports/run-001/traceability.md --json results/run-001/traceability.json
Continue with the full operating manual
Read-only evidence inspection is available through evidence validate, evidence explain, and MCP inspect_evidence. It checks bounded RunLedger integrity and an optional caller-supplied manifest digest. Authenticity, current-source applicability, and assurance remain explicitly not assessed. This adds one command beyond the historical 38-command baseline; it is admitted, not yet revision-bound complete.
- Installation and environment setup and a first positive/negative verification run
- Greenfield requirements and implementation and reviewed domain-to-source workflows
- Brownfield analysis and preservation and optimization
- Architecture and composition, security workflows, and specialist verification
- CI acceptance rules, interactive CLI, and troubleshooting
The manual preserves the detailed recipes and their pinned source references from 91c6790, with updated interface guidance. Its examples are templates; current admission data and the integration notes take precedence over historical backend or publication descriptions. The original edition remains available unchanged in the archive.
What is available
The live inventory maps 44 CLI commands and 244 argument declarations. Eighteen commands have admitted profiles: inspect, document-code, verify, verify-refactor, apply-refactor, analyze-codebase, generate-traceability-matrix, evidence, capabilities, read-only run show, worker artifacts, verify-bisimulation preflight, review-only security-exploit templates, static project validate/plan/impact, Java/JML contract extract/diff, Java assess-security, bounded validate-architecture, and typed V2 validate-domain. Additional scoped profiles connect V2 sessions and protected promotion to sequential Java contract generation and native ESC; full draft/implement parity remains partial. Revision-bound CI—not this static page—determines which complete-workflow claims passed for a particular commit.
Use the generated CLI inventory and generated strict capability reference for the exact static catalogue. The repository parity report is the human-readable baseline.
CI-qualified complete: 18/44 at cc7ba42. Its revision-bound CI artifact includes domain validation with 12 MCP cases and 11 CLI comparisons. The completion evaluator reproduced that report from downloaded evidence. This historical qualification does not cover later implementation changes; the checked-in current baseline remains evidence-free.
The prior Pages manual is retained as the 91c6790 historical edition. It describes the earlier two-tool Java-only pilot and is not current operational guidance.
Inspect contract surfaces before review
formalspecgen contract diff before/Account.java --candidate after/Account.java --json -
{"source": "before/Account.java", "operation": "diff", "candidate": "after/Account.java"}
MCP exposes inspect_contract; CLI contract extract inspects one source. Both use the shared refactor-gate parser and bounded, read-only source capture. Structural surface differences are not a semantic proof that contracts strengthened or weakened. Equal surfaces do not accept a refactor or establish equivalent behavior. Results remain NO_PROOF, with review unassessed and no execution, provider call, export, or approval. See the Java/JML scope and limits.
Plan explicit project inputs without executing workflows
formalspecgen project plan project.json --target app --json -
{"manifest": "project.json", "operation": "plan", "target": "app"}
formalspecgen project impact project.json --changed lib/S.java --json -
{"manifest": "project.json", "operation": "impact", "changed_paths": ["lib/S.java"]}
impact explains affected targets through declared source, contract and dependency links. Changed paths are relative to the manifest directory; repeat --changed for up to 128 unique paths. It requires the full project (no --target). A manifest change affects every target; unmapped changes block the request. Missing current inputs fail capture. This is not a Git diff, evidence-reuse authorization, or proof that other targets are independent.
MCP exposes inspect_project; the CLI also supports project validate. Both capture a versioned JSON manifest and explicit selected source/contract files under the current workspace. --target includes declared dependencies; omit it for all targets. Results bind captured byte digests and installed registry metadata, report unavailable profiles, and order dependencies before dependents.
This is a static declaration plan, not an executable plan. It does not probe tools, run builds, resolve imports, contact providers, or write artifacts. Listed contracts are not authenticated approvals. Requested budgets, output roots and assurance are declarations, not permission grants or proof claims. Every result remains NO_PROOF; readiness, assurance and contract approval remain NOT_ASSESSED. See the manifest format and limits.
Generate security review templates without running them
formalspecgen security-exploit report.json Target.java --out-dir review
The equivalent admitted security_exploit MCP call is:
{"report_path": "report.json", "target": "Target.java", "out_dir": "review"}
Both interfaces capture the report and target with a combined 4 MiB allowance, two regular files, at most 256 findings and 32 path components. Repeated lexical matching is bounded by target bytes multiplied by finding count (16 MiB). No compiler, scanner, provider, or generated template is executed.
Java supports the existing CWE-125, 89, 22, 502, 190, 476, 78, 798, 79, 326 and 732 review templates. Rust and C/C++ source/header forms support the existing CWE-125 bounds template only. Other findings remain listed as unsupported; they are not evidence of a clean target. Templates are generic starting points and may need editing before they even compile.
claim: NO_PROOF, exploit_proven: false, executed: false and unreviewed status remain explicit. A captured report digest does not authenticate its findings or prove that they apply to the supplied target. Partial generation retains every unsupported finding.
The default verdict is <out_dir>/poc-verdict.json. CLI --json PATH or MCP result_export selects a different new destination; "-" suppresses the verdict file (CLI emits JSON stdout, MCP returns its structured result). MCP outputs use the configured output root. All files are no-replace, and returned paths/digests come from publication metadata. Negative outcomes can be exported; an export failure may leave validly published, still-unreviewed templates while the request remains unsuccessful. See the manual recipe.
Validate a generated architecture model
formalspecgen validate-architecture plans/architecture.json --timeout 120 --json architecture-result.json
The admitted MCP tool validate_architecture shares the same bounded service:
{"artifact_path": "plans/architecture.json", "timeout": 120, "result_export": "architecture-result.json"}
One captured JSON input is schema-checked, lowered into TLA/CFG and checked by isolated TLC. The immutable bundle binds the source digest, generated model bytes, finite bounds, both provenance/check observations and admission policy. Returned model paths come from the actual publication map.
BOUNDED_ARCHITECTURE_EVIDENCE concerns generated TypeOK and default TLC deadlock checking—not operation contracts, use-case ordering, external behavior, source correspondence, liveness or specification adequacy. Unresolved domain references and ambiguous flattened names are rejected before execution. Validation is not human approval.
Input, JSON structure, model expansion, state-space and execution budgets are bounded. Failures remain NO_PROOF and may be exported. Outputs never replace files; publication failure leaves the request unsatisfied. CLI --json - writes stdout, retaining evidence under .formalspecgen/cli-output; MCP uses its designated root. See the manual recipe and revision-bound acceptance status; later changes require fresh evidence.
Assess Java with separate formal and SAST evidence
formalspecgen assess-security src/Counter.java --json security-verdict.json
Equivalent admitted MCP tool: assess_security.
{"source": "src/Counter.java", "run_sast": true, "result_export": "security-verdict.json"}
Both interfaces capture the bounded source once and use private copies for isolated OpenJML ESC and configured local Semgrep rules. The immutable bundle binds input digests, rule snapshots, actual stage observations, admission and limits. A later stage failure cannot erase earlier evidence.
CHECKS_PASSED is not security proof: the overall claim remains NO_PROOF, with the formal claim reported separately. Findings return SECURITY_FINDINGS; missing tools, isolation failures and incomplete scans remain unsuccessful. CLI --no-sast (MCP run_sast: false) can satisfy an explicitly reduced request and reports FORMALLY_VERIFIED_SAST_SKIPPED, never a complete scan.
CLI and MCP default to a new security_verdict.json. CLI --json - and MCP result_export: null suppress the result-file export but retain evidence publication. MCP files stay under the configured output root. Exports and evidence never replace existing files; negative reports can be exported. See the direct CLI recipe. Completion awaits provisioned revision-bound acceptance.
Mapping and public-surface preflight—not equivalence proof
formalspecgen verify-bisimulation Legacy.java candidate mapping.json --json -
The admitted verify_bisimulation MCP tool uses the same bounded service:
{"baseline": "Legacy.java", "refactored": "candidate", "mapping": "mapping.json", "result_export": "preflight/result.json"}
Capture includes a baseline, a nonempty state-to-class JSON mapping, and either one candidate file or the sorted top-level .java files in a candidate directory. Aggregate limits are 4 MiB, 256 files, 4,096 directory entries and 32 path components. Inputs are UTF-8 regular files; symlinks are rejected. Each captured input has its original path, role, byte count and digest recorded.
BISIMULATION_PREFLIGHT_READY means only that mapped class names occur and the legacy lexical public-method signatures match. It is not Java parsing, type checking, contract preservation, behavioral equivalence, or heap-topology proof. The legacy contract_surface_preserved field records only that lexical comparison. Every outcome is NO_PROOF; no executable or provider runs.
CLI --json - renders a result envelope; a filename requests a no-replace export. MCP exports stay beneath the configured output root. Negative results can be exported, but unsafe destinations and missing write permission cannot. Publication failure leaves the request unsatisfied and preserves existing files. See the preserved manual recipe.
Read worker artifact references without retrieving them
formalspecgen worker artifacts work-001 --json -
The equivalent MCP query is get_work_artifacts:
{"work_item_id": "work-001"}
The operator configures FORMALSPECGEN_A2A_POLICY, FORMALSPECGEN_A2A_STATE_ROOT, and FORMALSPECGEN_A2A_PRINCIPAL outside request arguments. Policy and state must be protected absolute paths outside the workspace. Environment settings are not authentication; use the deployment's principal and OS protections.
Exit zero means the local query succeeded. The nested worker_result equals the MCP result apart from admission metadata and retains task status, references, recorded digests, pending acceptance and coordination diagnostics. An inconsistent task can be read successfully while its nested result remains unsatisfied. NO_PROOF, implementation_accepted: false, artifact_retrieval_performed: false, and artifact_bytes_validated: false remain explicit.
URIs are untrusted data, not instructions or read authority. No remote refresh, URI fetch, patch staging, verification, publication, or lifecycle mutation occurs. An empty reference list does not resolve dispatch uncertainty. Reading a stored digest does not validate artifact bytes. See the CLI recipe; trusted artifact retrieval and integration are separate work.
Inspect an existing supervised run
formalspecgen run show review-001 --json -
The equivalent MCP operation is get_agent_run:
{"run_id": "review-001"}
Both use the same principal-owned store, event-chain and review-digest checks. The operator configures FORMALSPECGEN_AGENT_STATE_ROOT as a protected absolute directory outside the workspace and FORMALSPECGEN_AGENT_PRINCIPAL as the deployment identity. These are not request arguments; environment configuration is not itself authentication.
CLI exit zero and RUN_READ mean retrieval succeeded, even for a failed, blocked or cancellation-pending run. Its run_result retains the MCP result (excluding admission metadata), including the original claim and goal satisfaction. Missing, unauthorized or corrupt records fail. Reading does not execute, retry, resume, cancel, sign, approve, or create state. File export and CLI lifecycle mutations are not supported in this slice.
See the direct CLI recipe. Reading a recorded claim does not re-establish applicability or authorize integration.
Discover capability profiles without running probes
formalspecgen capabilities verify --json -
The equivalent MCP tool is describe_capabilities:
{"name": "verify"}
Omit the name to list the installed built-in registry. Exact registry, CLI and MCP identifiers are accepted; unknown or ambiguous identifiers fail. The report includes declared modes, languages, backends, effect ceilings, providers and claim boundaries, bound to a registry digest.
This is static metadata, not live readiness or a permission grant. No workspace configuration/plugins, tools or providers are consulted. Completion and readiness remain NOT_ASSESSED; the claim is NO_PROOF. Profiles may include explicit rejection paths and do not guarantee support for a particular source. Use the generated CLI inventory for parser coverage and the operating recipe for direct use.
Strict MCP catalogue
The table below is rendered from mcp_capabilities.json, which is generated from the capability registry and Python handler signatures. Runtime discovery is separately exercised by mandatory MCP acceptance jobs.
| Tool | Catalogue | Isolation | Profiles |
|---|---|---|---|
| Loading generated capability data… | |||
Bounded repository analysis
analyze_codebase captures Java, Rust, C, C++, header, and LLVM IR inputs under aggregate byte, file, traversal-entry, and depth limits. It rejects symlink traversal, runs the extractor against a private snapshot, and publishes architecture and domain candidates without replacement.
{
"target_dir": "src",
"out_dir": "analysis/current",
"project_root": "analysis-project",
"result_export": "results/analysis.json"
}
The result binds the captured source manifest to the published artifact digests. Every generated model remains unreviewed; repository analysis does not run code, invoke a provider, or prove source behavior.
Requirements traceability
Call generate_traceability_matrix to match REQ-numbered requirements to domain invariants and source lines. Candidate YAML/JSON and reviewed JSON domains are supported. Matching is deterministic field/bound matching, not proof that a requirement holds; unmapped requirements remain visible.
{
"domain": "domain.yaml",
"source": "src",
"requirements": "requirements.req",
"out": "reports/traceability.md"
}
The example also publishes reports/traceability.json. Use result_export to choose a different JSON path. Both destinations are relative to the configured MCP output root and never replace existing files. Follow the returned matrix_file and publication metadata; source references are relative to the captured source root, with their digests recorded. Negative outcomes can publish JSON too; an export failure leaves any committed Markdown intact but makes the request unsuccessful.
Capture is limited to 8 MiB across domain, requirements, and sources, 514 total files, 4096 traversal entries, and depth 32. Matching and combined report output are also bounded. No provider, compiler, or verifier is invoked.
Inspect existing evidence
Use CLI or MCP to inspect a RunLedger v1 manifest without rerunning verification or changing artifacts. The manifest and its inventory are captured under aggregate 8 MiB / 256-file limits. Integrity is separate from authenticity, current-source applicability, and assurance; those three remain NOT_ASSESSED. An optional expected digest is caller-supplied, not human authentication.
formalspecgen evidence explain run/evidence/manifest.json --json -
The equivalent inspect_evidence MCP payload is:
{
"manifest": "run/evidence/manifest.json",
"operation": "explain"
}
The result reports recorded claims without endorsing them; its own claim is always NO_PROOF. This command has no file-export option. CI acceptance uses synthetic ledgers and actual CLI/MCP calls, not backend proof execution. Completion remains conditional on trusted, revision-bound acceptance.
Compare two captured ledgers with diff. The 8 MiB / 256-file allowance applies to both inputs together. It reports inventory-byte and recorded-terminal changes, not semantic equivalence or proof applicability. If either input fails validation, no comparison is claimed; a successfully validated baseline remains visible.
formalspecgen evidence diff baseline/evidence/manifest.json --comparison-manifest candidate/evidence/manifest.json --json -
{
"manifest": "baseline/evidence/manifest.json",
"operation": "diff",
"comparison_manifest": "candidate/evidence/manifest.json"
}
Optional expected_sha256 and comparison_expected_sha256 pin the two manifest byte digests independently; neither authenticates an author. Comparison inputs are rejected for non-diff operations.
Optional primary-source checking is available for validate and explain, not diff. It accepts recognized verification receipts whose terminal, proof-stage and primary snapshot identities agree. Other schemas, including multisource refactor receipts, fail explicitly. Only the caller's explicit source path is read, never a path merely named inside the receipt.
formalspecgen evidence validate run/evidence/manifest.json --source src/Counter.java --json -
{
"manifest": "run/evidence/manifest.json",
"operation": "validate",
"source": "src/Counter.java"
}
The source shares the aggregate 8 MiB / 256-file capture allowance. A match reports SOURCE_MATCH_ONLY, not full applicability: dependencies, toolchain, assumptions, admission policy and source context are unchecked. Changed bytes report SOURCE_CHANGED; failed checking retains receipt integrity but leaves applicability unestablished. Authenticity and assurance remain unassessed. Matching bytes cannot turn a recorded verification failure into success.
Multi-language verification
verify_code accepts source, mode, backend, and optional result_export. The server derives language from the source and admits only declared combinations.
Java / JML
OpenJML parse, check, and ESC. Successful ESC may produce a deductive-proof claim under its recorded assumptions.
Rust
Rust checking plus Prusti or Kani. Kani retains bounded-evidence limits.
C / ACSL
Frama-C ESC through strict execution. Unsupported modes fail explicitly.
C++
ESBMC with recorded bounds. A bounded result is never presented as unbounded proof.
{
"source": "src/Counter.java",
"mode": "esc",
"result_export": "verification/counter.json"
}
Omit backend for Java/JML, C, and C++; the server derives those backends from the source. Use backend only to select prusti or kani for Rust.
Exports are new artifacts under the configured MCP output root. Existing destinations are not replaced. Tool startup, sandbox, resource, or publication failures remain NO_PROOF.
Contract-preserving refactoring
verify_refactor compares a reviewed baseline with a candidate file or collaborator directory, preserves contract/proof-trust/semantic-context checks, and verifies both sides using the strict executor. Its evidence bundle binds both snapshots and all actual execution observations.
The strict MCP profile captures at most 4 MiB across at most 256 source files. Capture consumes the aggregate byte budget while reading, before any verifier is invoked.
{
"baseline": "src/Counter.java",
"refactored": "candidate/Counter.java",
"result_export": "refactor/counter.json",
"signing_intent": false
}
Java/JML, Rust, C, and C++ profiles are admitted. For signing, set signing_intent to true and provide a fresh result_export. The server first completes unsigned verification and publication, then returns an artifact-bound APPROVAL_REQUIRED request.
{
"baseline": "src/Counter.java",
"refactored": "candidate/Counter.java",
"result_export": "refactor/counter-to-sign.json",
"signing_intent": true
}
An authorized reviewer signs the exact approval decision outside MCP. The complete_refactor_signing tool can then invoke only the operator-configured protected signer; it returns a detached signature and receipt without exposing either private key. Signing records approval but does not strengthen the verification claim.
Applying a deterministic refactor
apply_refactor captures the source and inspection inputs, prepares the candidate in private staging, and runs the same strict preservation service before publishing new candidate files. Java/JML supports the declared deterministic patterns; Rust supports extract-method and strategy; C and C++ support extract-method. Candidate artifacts remain unreviewed even when preservation succeeds.
{
"source": "src/Counter.java",
"method": "increment",
"out": "candidates/Counter.java",
"pattern": "extract-method",
"inspection": "inspection/counter.json",
"result_export": "refactor/counter-applied.json"
}
All output paths are relative to the designated MCP output root and use no-replace publication. Transformation rejection, verifier failure, sandbox failure, or publication failure remains NO_PROOF; successful preservation does not establish general behavioral equivalence.
Inspection and documentation
Inspection
{
"source": "src/Inventory.java",
"result_export": "inspection/inventory.json"
}
Inspection is an unreviewed analysis result, not proof. Omit result_export for a read-only invocation.
Documentation
Documentation defaults to provider-assisted operation: no_llm=false and provider="ollama". Use no_llm: true when source-derived material must remain provider-free.
{
"source": "src/Inventory.java",
"out": "docs/inventory.md",
"project_root": "inventory-docs",
"no_llm": true,
"result_export": "results/inventory.json"
}
Provider, model, and disclosure permissions are independently enforced. Generated documentation remains unreviewed and does not prove the described behavior.
A2A worker coordination
Four MCP coordination tools submit, observe, read artifact references, and cancel bounded worker tasks: submit_work_item, get_work_item, get_work_artifacts, and cancel_work_item. The reference-only query also has the worker artifacts CLI interface described above.
A worker result is a proposal. Task completion is not implementation acceptance, formal proof, or permission to merge. Protected paths, child authority attenuation, cancellation intent, terminal-state preservation, and uncertain dispatch remain controller-managed state.
Supervised agent runs
The MCP-only supervisor tools are start_agent_run, get_agent_run, resume_agent_run, and cancel_agent_run. The model proposes typed actions; the trusted gateway authorizes effects and invokes admitted services.
Human authority in either interface
Interface choice does not grant approval authority. Models may propose changes or request an approval; an authenticated human decision must authorize protected signing. A valid signature authenticates the approved artifact without strengthening its verification claim.
Implemented protected continuation: MCP refactor signing publishes unsigned evidence, creates an exact approval request, and exposes status/completion tools. The reviewer records an authenticated decision outside MCP through python -m pipeline.approval_service; the protected signer keeps private keys outside the MCP process. Follow the approval-policy-v2 operator procedure.
Not yet a universal approval bridge: promote-domain, sign-artifact, manage-trust, and direct CLI verify-refactor --signing-key are human-operated interfaces, not automatic clients of that protected continuation. Do not give these local privileges or keys to an agent, or imply that all trust operations are MCP-admitted. Use the authenticated service where supported and require explicit human authorization for remaining local trust operations.
Evidence and operational checks
Consumers must separately check the workflow outcome, enforced execution policy, source identity, and publication receipt. A successful model or worker message is not authoritative evidence.
The last reviewed coordination baseline was d9f370b, with public CI run 36211006530. New completion claims must point to their own tested revision and CI artifact; the static Pages build does not create such evidence.