CLI Reference

24 commands.

audit key certify registry verify receipt gate proxy gauge diagnose check scan witness bridge serve discover manifest init infer pack merge hosts frameworks import

$ pip install bulla
$ bulla --help

`audit`#

Scan an MCP config file, launch all configured servers, and diagnose cross-server coherence. Auto-detects configs from Cursor, Claude Code, Cline, Claude Desktop, OpenAI Codex, Windsurf, and Zed. The primary entry point for most users.

bulla audit [config] [options]

Flag	Description
`--host NAME`	Force a specific MCP host (cursor, claude-code, cline, claude-desktop, codex, zed, windsurf)
`--format {text,json,sarif}`	Output format (default: text)
`-v, --verbose`	Show full blind spot details
`--max-fee N`	Exit 1 if coherence fee exceeds N (CI gating)
`--max-blind-spots N`	Exit 1 if blind spots exceed N
`--discover`	Run LLM-powered convention discovery before auditing
`--converge`	Iterative convergence loop (fee strictly decreases per round)
`--receipt FILE`	Write a WitnessReceipt JSON after auditing
`--chain RECEIPT.json`	Chain onto a prior receipt's vocabulary
`--pack FILE`	Additional convention pack YAML (repeatable)

$ bulla audit
$ bulla audit --host claude-code
$ bulla audit ~/.cursor/mcp.json --format sarif -o report.sarif
$ bulla audit --discover --converge --receipt audit.json

`key`#

Generate a local ed25519 did:key identity your agent signs deeds under. Bulla never mints the name; it signs under one you hold.

bulla key gen [options]

Flag	Description
`-o FILE`	Write the key to FILE

$ bulla key gen -o key.json

`certify`#

Emit a signed, recomputable coherence certificate (a deed) for a composition. The verdict is a deterministic function of the composition — anyone can re-run it and get the same answer.

bulla certify --sign composition.yaml [options]

Flag	Description
`--sign`	Sign the certificate with your key
`--key FILE`	The did:key identity to sign under
`--output FILE`	Write the certificate JSON
`--format {text,json}`	Output format

$ bulla certify --sign comp.yaml --key key.json --output deed.json --format json

`registry`#

The append-only RFC 6962 Merkle log: append deeds, print the log, produce inclusion/consistency proofs, anchor the root via OpenTimestamps, or serve read-only HTTP endpoints (/root, /inclusion, /by-composition).

bulla registry {append,log,prove,root,anchor,serve} [options]

Flag	Description
`--log FILE`	The log file to operate on

$ bulla registry append deed.json --log log.jsonl
$ bulla registry root --log log.jsonl

`verify`#

Verify a certificate: integrity, authenticity, anchor, inclusion. Refuses a host’s bare claim about its own root — inclusion counts only against a root you obtained independently.

bulla verify CERT [options]

Flag	Description
`--registry URL\|FILE`	Registry to check inclusion against
`--trusted-root HASH`	A root you pinned independently of the host

$ bulla verify deed.json --registry log.jsonl --trusted-root <hash>

`receipt`#

Verify an ActionReceipt to the digest rung: the four hashes recompute and the modality law holds. The same checks run in the in-browser verifier on /spec.

bulla receipt verify RECEIPT.json

$ bulla receipt verify receipt.json

`gate`#

The recourse gate: PROCEED / REFUSE-with-cure on a counterparty’s signed, logged deed. Gates on type signals only — coherence (fee=0), authenticity, and inclusion under an independently trusted root. Exit code is the verdict.

bulla gate --certificate DEED --registry LOG [options]

Flag	Description
`--certificate FILE`	The deed to gate on
`--registry URL\|FILE`	Where inclusion is checked
`--disclose DIM`	Apply a convention disclosure as the cure

$ bulla gate --certificate deed.json --registry log.jsonl

`proxy`#

Live MCP proxy: fronts N backend servers as one, namespaces tools as server__tool, and injects the eight bulla__* meta-tools the agent itself calls (five advisory, three deed). Observe mode — never modifies traffic.

bulla proxy --config servers.yaml [options]

Flag	Description
`--config FILE`	Backend server config
`--inject-prompt`	Inject the agent system prompt for meta-tool use

$ bulla proxy --config servers.yaml

`gauge`#

Diagnose a single MCP server or manifest with prescriptive disclosure. Useful for server authors checking their own tool conventions.

bulla gauge [manifest] [options]

Flag	Description
`--mcp-server CMD`	Shell command to start MCP server
`--format {text,json,sarif}`	Output format
`-v, --verbose`	Show blind spot details and bridge recommendations
`--pack FILE`	Additional convention pack YAML

$ bulla gauge tools.json
$ bulla gauge --mcp-server "npx @modelcontextprotocol/server-filesystem /"

`diagnose`#

Run full diagnostic on composition YAML files. Reports coherence fee, blind spots, and bridge recommendations.

bulla diagnose [files...] [options]

Flag	Description
`--format {text,json,sarif}`	Output format
`--brief`	One-line-per-file summary (fee + blind spot count)
`--examples`	Run on bundled example compositions
`--pack FILE`	Additional convention pack YAML

$ bulla diagnose composition.yaml
$ bulla diagnose compositions/ --brief

`check`#

CI/CD gate. Exits with code 1 if compositions exceed configured thresholds. Use in GitHub Actions or any CI pipeline.

bulla check [files...] [options]

Flag	Description
`--max-fee N`	Exit 1 if coherence fee exceeds N
`--max-blind-spots N`	Max blind spots before failing (default: 0)
`--max-unbridged N`	Max unbridged edges before failing (default: 0)
`--format {text,json,sarif}`	Output format

$ bulla check --max-fee 0 compositions/
$ bulla check --max-blind-spots 3 --format sarif composition.yaml

`scan`#

Scan live MCP servers via stdio transport and diagnose. Zero-config: just provide the shell commands to start the servers.

bulla scan <commands...> [options]

Flag	Description
`--format {text,json,sarif}`	Output format
`-o, --output FILE`	Save inferred composition YAML
`--pack FILE`	Additional convention pack YAML

$ bulla scan "npx @mcp/server-filesystem /" "npx @mcp/server-github"

`witness`#

Diagnose and emit a tamper-evident WitnessReceipt. Binds composition, diagnostic, and policy into a content-addressed, DAG-chainable JSON object.

bulla witness <files...>

$ bulla witness composition.yaml

`bridge`#

Auto-generate bridged compositions or JSON patches. Produces patched YAML where hidden conventions are surfaced as observable schema annotations.

bulla bridge <files...> [options]

Flag	Description
`--format {yaml,json-patch}`	Output: bridged YAML (default) or JSON patches
`-o, --output FILE`	Write output to file

$ bulla bridge composition.yaml
$ bulla bridge composition.yaml --format json-patch -o patches.json

`serve`#

Run Bulla as an MCP server (stdio transport). Exposes bulla.witness and bulla.bridge as MCP tools, and bulla://taxonomy as a resource.

bulla serve

$ bulla serve

`discover`#

Discover convention dimensions from tool schemas using an LLM. Generates a micro-pack YAML that can be loaded with --pack.

bulla discover --manifests DIR -o FILE [options]

Flag	Description
`--manifests DIR`	Directory of MCP manifest JSON files
`-o, --output FILE`	Output micro-pack YAML file
`--provider {openai,anthropic,openrouter,auto}`	LLM provider
`--pack FILE`	Additional convention pack YAML

$ bulla discover --manifests ./manifests -o discovered.yaml --provider anthropic

`manifest`#

Generate, validate, or publish Bulla Manifest files. Optionally anchor to the Bitcoin timechain via OpenTimestamps.

bulla manifest [options]

Flag	Description
`--from-json FILE`	Generate from MCP manifest JSON
`--from-server CMD`	Generate from a live MCP server
`--validate FILE`	Validate an existing manifest YAML
`--publish FILE`	Anchor to Bitcoin timechain (requires bulla[ots])
`--verify FILE`	Verify OTS proof on a published manifest

$ bulla manifest --from-server "npx @mcp/server-filesystem /" -o fs.yaml
$ bulla manifest --validate fs.yaml

`init`#

Interactive wizard to generate a composition YAML from scratch.

bulla init [-o OUTPUT]

$ bulla init -o my-composition.yaml

`infer`#

Infer a proto-composition YAML from an MCP manifest JSON. Classifies tool parameters against known convention dimensions.

bulla infer <manifest> [options]

Flag	Description
`-o, --output FILE`	Write output to file
`--pack FILE`	Additional convention pack YAML

$ bulla infer tools.json -o composition.yaml

`pack`#

Convention pack utilities. Currently supports validation.

bulla pack validate <file>

$ bulla pack validate my-dimensions.yaml

`merge`#

Merge vocabularies from multiple receipts. Produces a DAG receipt with parent_receipt_hashes linking the inputs.

bulla merge <receipts...> [options]

Flag	Description
`--receipt FILE`	Write merged receipt JSON to file
`--format {text,json}`	Output format

$ bulla merge receipt-a.json receipt-b.json --receipt merged.json

`hosts`#

Inspect MCP host integrations. Lists all seven registered hosts (Cursor, Claude Code, Cline, Claude Desktop, OpenAI Codex, Zed, Windsurf) and shows which configs are present on the current system.

bulla hosts list

$ bulla hosts list

`frameworks`#

Inspect framework adapters. Lists all registered framework adapters (Anthropic Messages, LangGraph, CrewAI) and their parse-mode support.

bulla frameworks list

$ bulla frameworks list

`import`#

Convert framework-native tool definitions into a Bulla manifest. Pipe through `bulla audit` directly with --audit, or write a manifest JSON for later. Static AST parsing today; runtime mode reserved for a future sprint.

bulla import <framework> <source> [options]

Flag	Description
`--out FILE`	Write manifest JSON to FILE (default: stdout)
`--audit`	Pipe through bulla audit immediately, no intermediate file
`--format {text,json,sarif}`	Audit output format (only relevant with --audit)
`--mode {static,runtime}`	Parse mode (default: static; runtime reserved for future sprint)

$ bulla import langgraph workflow.py --out manifest.json
$ bulla import crewai agents/ --audit
$ bulla import anthropic-messages tools.json --audit --format sarif

← PreviousDemosExact, surrogate, and comparison.

audit#

key#

certify#

registry#

verify#

receipt#

gate#

proxy#

gauge#

diagnose#

check#

scan#

witness#

bridge#

serve#

discover#

manifest#

init#

infer#

pack#

merge#

hosts#

frameworks#

import#