CLI vs MCP Coverage

When building Ironflow applications with an AI assistant (Claude Code, Cursor, etc.), the AI can interact with your Ironflow server through two channels:

• CLI — The AI runs ironflow commands via the terminal (like it runs gh, git, npm)
• MCP — The AI calls structured MCP tools directly (requires .mcp.json configuration)

The Ironflow agent for Zed and JetBrains uses both: the CLI through its shell tool, and a fixed set of MCP tools. It starts a local ironflow mcp process, which works under ironflow serve --dev, and falls back to the server’s remote MCP endpoint. If neither works, it uses the CLI only.

Both hit the same underlying API for operations. MCP also exposes API contracts and bundled authoring guides. The difference is coverage, output format, and interaction style. In addition to the static MCP tools listed below, with --allow-writes the MCP server also surfaces dynamic agent tools registered by SDK clients at runtime — so the effective MCP tool count may be higher depending on your project. (Read-only mode never exposes them; pass --static-only to exclude them in write mode.) Desktop’s optional terminal bridge tools are outside the core counts below.

MCP is read-only by default

ironflow mcp registers 27 read-only tools. The 16 write tools — ironflow_emit_event, ironflow_invoke_function, ironflow_append_entity_event, ironflow_delete_stream, ironflow_kv_put, ironflow_secret_set, ironflow_cancel_run, ironflow_delete_run, ironflow_resume_run, ironflow_rebuild_projection, ironflow_outbox_dlq_requeue, ironflow_outbox_dlq_discard, ironflow_circuit_breaker_reset, ironflow_redact_event, ironflow_redact_run, ironflow_redact_step — only appear when you start the server with ironflow mcp --allow-writes. Every MCP row in the tables below that mutates state is gated behind that flag.

The four operator read verbs — ironflow_dead_letter_list, ironflow_outbox_dlq_list, ironflow_circuit_breaker_list, ironflow_rebuild_projection_status — are available without write access. The dead_letters list reads stored rows; automatic capture covers scoped routing and resume failures, projection decoding and SQL apply failures, and best-effort system event publish failures. An empty list does not rule out routing, projection, or publishing failures.

One further tool, ironflow_await_reload, needs both --allow-writes and --evidence-file — it rides on the same per-emit version fetch the evidence trail already pays for.

Quick Comparison

	CLI (via Bash)	MCP (via tools)
Tools / commands	Every top-level command in ironflow --help	27 read-only, 43 with --allow-writes, 44 with --evidence-file too
Coverage	Everything except KV, overview stats, worker listing, documentation retrieval, and the reload barrier	A subset, including authoring guides, run resume, projection rebuild, outbox DLQ and circuit breakers (+ dynamic agent tools)
Discoverability	ironflow --help, ironflow emit --help	AI sees all tools at startup
Output format	Text (AI parses it)	Structured JSON
Setup required	None — just binary in PATH	.mcp.json config file
Transport	Local process	stdio (default) or --transport streamable-http
Shell escaping	JSON in bash can be tricky	Native JSON parameters
Sync operations	--wait blocks until the run completes	ironflow_wait_for_run blocks until a run finishes
Recommendation	Primary tool for development	Supplement for documentation, KV, and overview

Core Operations

Operation	CLI	MCP	Notes
Emit event	ironflow emit order.placed --data '{...}'	ironflow_emit_event
Emit + wait for result	ironflow emit ... --wait	ironflow_emit_event, then ironflow_wait_for_run per run ID	Critical for test loops
Retry without duplicates	ironflow emit ... --idempotency-key <key>	idempotency_key argument	Same key, same event: a retry after a timeout never emits twice. Also on invoke / ironflow_invoke_function, and on ironflow_append_entity_event (with expected_version)
Emit from file	ironflow emit ... --data-file payload.json	—	CLI only
Invoke function	ironflow invoke process-order --data '{...}'	ironflow_invoke_function	CLI waits by default (--timeout, default 30s); MCP returns at once, so follow with ironflow_wait_for_run
Invoke without waiting	ironflow invoke ... --no-wait	ironflow_invoke_function
List runs	ironflow run list	ironflow_list_runs
Filter runs by status	ironflow run list --status failed	ironflow_list_runs with status
Filter runs by function	ironflow run list --function my-func	ironflow_list_runs with function_id
Get run details	ironflow run get <run-id>	ironflow_get_run
Wait for a run to finish	ironflow run wait <run-id>	ironflow_wait_for_run	Both poll, so giving up never cancels the run
Get run steps	ironflow run get <run-id> (includes step outputs)	ironflow_get_run_steps
Cancel run	ironflow run cancel <run-id>	ironflow_cancel_run
Delete run	ironflow run delete <run-id>	ironflow_delete_run	Terminal runs only, irreversible. The CLI prompts unless --yes; the MCP tool asks the user to confirm, or takes confirm: true when the client cannot be asked
Prune runs by filter	ironflow run prune --status completed	—	CLI only — the filter can match an environment’s whole history, so it is deliberately not an MCP tool
Retry / resume run	ironflow run resume <run-id>	ironflow_resume_run	One verb handles both paused and failed runs; --from-step / from_step targets a specific step. There is no separate retry command.
Pause run	ironflow run pause <run-id>	—	CLI only
Inject step output	ironflow run inject <run-id> <step-id> --output '{...}'	—	CLI only
View paused state	ironflow run paused-state <run-id>	—	CLI only
TUI debugger	ironflow inspect <run-id>	—	CLI only (interactive)
SQL query	ironflow sql "SELECT ..."	ironflow_sql_query
SQL with format	ironflow sql "..." --format json	—	CLI only (table, json, csv, jsonl)

Event Sourcing

Operation	CLI	MCP	Notes
List entity streams	ironflow stream list	ironflow_list_entity_streams
Filter by type	ironflow stream list --type Order	—	CLI only
Read stream events	ironflow stream read order-1	ironflow_read_entity_stream
Stream info	ironflow stream info order-1	—	CLI only
Append event	ironflow stream append order-1 --type Order --event order.placed --data '{...}'	ironflow_append_entity_event
Delete entity stream	ironflow stream delete order-1 [--purge]	ironflow_delete_stream	Appends a $stream.deleted tombstone and drops snapshots; --purge / purge: true also deletes the events below it. Irreversible. The CLI prompts unless --yes; the MCP tool asks the user to confirm, or takes confirm: true when the client cannot be asked
Redact event payload	ironflow event redact ev-1	ironflow_redact_event	Replaces the data with a placeholder; the row, its name and its entity version stay. Does not reach the runs it triggered. Irreversible
Redact run payloads	ironflow run redact run-1	ironflow_redact_run	Replaces input, output and every audit payload for the run and its steps. Terminal runs only. Irreversible
Redact step output	ironflow run redact-step <step-row-id>	ironflow_redact_step	Replaces output and original output, plus that step’s audit payloads. Takes the row id, not the step name. Irreversible
Subscribe to stream	ironflow stream subscribe order-1	—	CLI only

Projections

Operation	CLI	MCP	Notes
List projections	ironflow projection list	ironflow_list_projections
Get projection state	ironflow projection get my-proj	ironflow_projection_status
Projection status	ironflow projection status my-proj	ironflow_projection_status
Rebuild projection	ironflow projection rebuild my-proj	ironflow_rebuild_projection	Asynchronous — returns a job. Destructive. Both accept a dry run (--dry-run / dry_run: true) that reports the scope and changes nothing. Do it first
Rebuild progress	ironflow projection status my-proj (includes rebuild progress)	ironflow_rebuild_projection_status	Events processed, total, ETA. The MCP tool reports the rebuild job only; ironflow_projection_status reports the projection
Cancel rebuild	ironflow projection rebuild cancel my-proj	—	CLI only
Resume projection	ironflow projection resume my-proj	—	CLI only
Watch projection	ironflow projection watch my-proj	—	CLI only (live updates)
Pause projection	ironflow projection pause my-proj	—	CLI only
Archived definitions	ironflow projection history my-proj	—	CLI only
Delete projection	ironflow projection delete my-proj	—	CLI only
Create SQL projection	ironflow projection create ...	—	CLI only
Wait for catch-up	ironflow projection wait my-proj	—	CLI only — blocks until the projection is caught up
Wait for a specific event	ironflow projection wait-for-event <event-id> --projection my-proj	—	CLI only (--projection is required)
Wait for several projections	ironflow projection wait-batch ...	—	CLI only
Inspect pre-#1516 JetStream durables	ironflow projection durables prune	—	CLI only (migration) — lists candidates and stops
Prune pre-#1516 durables	ironflow projection durables prune --delete	—	CLI only (migration) — --delete is what actually removes them

Contracts and authoring guidance

Operation	CLI	MCP	Notes
Retrieve REST OpenAPI	—	ironflow_get_docs(topic: "openapi") or ironflow://docs/openapi	Fetched from the configured engine; REST only, excludes ConnectRPC methods and push callbacks, not the complete Ironflow API contract
Retrieve push wire protocol	—	ironflow_get_docs(topic: "push-protocol") or ironflow://docs/push-protocol	Markdown bundled with the MCP binary; available offline
Retrieve SDKless handler guide	—	ironflow_get_docs(topic: "function-authoring") or ironflow://docs/function-authoring	Markdown bundled with the MCP binary; available offline

The guides may differ from the target engine’s version or the current website. All three resources and the documentation tool work in read-only mode and with --static-only. See the MCP guide for retrieval examples.

Functions

Operation	CLI	MCP	Notes
List functions	ironflow function list	ironflow_list_functions
Get function details	ironflow function get my-func	ironflow_get_function

Events & Schemas

Operation	CLI	MCP	Notes
Explain event routing	ironflow events explain	ironflow_explain_event_match	Read-only current eligibility
List events	(via sql or subscribe)	ironflow_list_events
List event schemas	ironflow event schema list	—	CLI only
Get schema	ironflow event schema get order.created	—	CLI only
Register schema	ironflow event schema register ...	—	CLI only
Delete schema	ironflow event schema delete <name>	—	CLI only
Archived schema definitions	ironflow event schema history <name> --version <n>	—	CLI only
Check schema enforcement	ironflow event schema check [event-name]	—	CLI only — reports per schema whether it is actually constraining traffic (enforcing, partial, unvalidated, unused, no-traffic, permissive, broken)
Test upcast	ironflow event upcast ...	—	CLI only

Storage

KV Store

Operation	CLI	MCP	Notes
List buckets	—	ironflow_kv_list_buckets	MCP only
List keys	—	ironflow_kv_list_keys	MCP only
Get value	—	ironflow_kv_get	MCP only
Put value	—	ironflow_kv_put	MCP only (write)

Note

KV store operations are currently only available via MCP (and the dashboard). There is no ironflow kv CLI command yet.

Secrets

Operation	CLI	MCP	Notes
List secrets	ironflow secret list	ironflow_list_secrets
Get secret metadata	ironflow secret get API_KEY	—	CLI only
Set secret	ironflow secret set API_KEY value	ironflow_secret_set
Delete secret	ironflow secret delete API_KEY	—	CLI only

Pub/Sub & Real-time

Operation	CLI	MCP	Notes
Subscribe to events	ironflow subscribe "system.run.>"	—	CLI only
List topics	ironflow topic list	—	CLI only
Topic stats	ironflow topic stats order.processed	—	CLI only
Publish to topic	ironflow topic publish ... --data '{...}'	—	CLI only

Infrastructure

Operation	CLI	MCP	Notes
Server health	ironflow server info	ironflow_server_info
Overview stats	—	ironflow_overview	MCP only
List projects	ironflow project list	ironflow_list_projects
Create project	ironflow project create my-proj	—	CLI only
Delete project	ironflow project delete proj_xxx	—	CLI only
List environments	ironflow env list	ironflow_list_environments
Create environment	ironflow env create staging	—	CLI only
Delete environment	ironflow env delete env_xxx	—	CLI only
List workers	—	ironflow_list_workers	MCP only (ironflow capacity sessions lists pull-worker sessions, but needs platform credentials)

Auth & Admin

Operation	CLI	MCP	Notes
List API keys	ironflow apikey list	—	CLI only
Create API key	ironflow apikey create my-key --role role_xxx	—	CLI only
Delete API key	ironflow apikey delete ak_xxx	—	CLI only
Rotate API key	ironflow apikey rotate ak_xxx	—	CLI only
Audit trail	ironflow audit trail <run-id>	—	CLI only
Auth audit	ironflow audit auth-trail --org org_default	—	CLI only

Circuit Breakers

Operation	CLI	MCP	Notes
List circuit breakers	ironflow circuit-breaker list	ironflow_circuit_breaker_list	Read tool — no --allow-writes needed
Reset circuit breaker	ironflow circuit-breaker reset <endpoint-url> or <function-id>	ironflow_circuit_breaker_reset	Different argument on each side: the CLI takes an endpoint URL or a function ID and resolves it against the list itself; the MCP tool takes the key field verbatim from ironflow_circuit_breaker_list

Stored dead-letter rows

Action	CLI	MCP tool	Notes
List stored dead-letter rows	ironflow dead-letters list	ironflow_dead_letter_list	Read tool. Explicit environment required. Optional exact source filter and bounded pagination. Structured output preserves stored payload bytes as base64.

Outbox

Operation	CLI	MCP	Notes
List dead-letter entries	ironflow outbox dlq list	ironflow_outbox_dlq_list	Read tool. env is required and must match your API key’s scope — a mismatch is a 403, not a silent redirect
Requeue dead-letter entry	ironflow outbox dlq requeue <eventID>	ironflow_outbox_dlq_requeue	env required. Acts on every row sharing the event_id
Discard dead-letter entry	ironflow outbox dlq discard <eventID>	ironflow_outbox_dlq_discard	env required. Irreversible, and acts on every row sharing the event_id — an entity append leaves two. The CLI prompts unless --yes; the MCP tool asks the user to confirm, or takes confirm: true when the client cannot be asked

RBAC & Policy Set

Operation	CLI	MCP	Notes
List roles	ironflow role list	—	CLI only
Get role	ironflow role get <role-id>	—	CLI only
Create/delete role	ironflow role create ... / ironflow role delete <role-id>	—	CLI only
Pull the policy set	ironflow policy pull <dir>	—	CLI only
Validate a policy set	ironflow policy validate <dir>	—	CLI only
Dry-run a policy set	ironflow policy dry-run [dir] --input <file>	—	CLI only
Push a policy set	ironflow policy push <dir>	—	CLI only
Policy-set versions / rollback	ironflow policy versions / ironflow policy rollback <version>	—	CLI only
Force a tenant set to monitor mode (platform break-glass)	ironflow policy force-monitor <org> --reason ...	—	CLI only

Organizations & Tenants

Operation	CLI	MCP	Notes
List organizations	ironflow org list	—	CLI only
Get organization	ironflow org get <org-id>	—	CLI only
Create/delete organization	ironflow org create ... / ironflow org delete <org-id>	—	CLI only
List tenants	ironflow tenant list	—	CLI only
Provision tenant	ironflow tenant provision ...	—	CLI only

Other CLI Commands

Operation	CLI	MCP	Notes
Initialize project	ironflow init	—	CLI only
Generate ironflow.yaml	ironflow config init	—	CLI only
Validate config	ironflow validate	—	CLI only
Show version	ironflow version	—	CLI only
List debounces	ironflow debounce list	—	CLI only
Cancel a debounce	ironflow debounce cancel <function-id> <key>	—	CLI only
Inspect dispatch capacity	ironflow capacity	—	CLI only — lanes, queue, leases, buckets, sessions, credits, stats
Write AI skills to disk	ironflow skills sync	—	CLI only
Detect coding agents	ironflow skills doctor	—	CLI only
Run the server and tools	ironflow serve, a2a, conformance, update, completion	—	CLI only
Ops / infra	platform, tenant, cloud	—	CLI only — platform, tenant and Cloud operations, not app development

Webhooks

Operation	CLI	MCP	Notes
List webhooks	ironflow webhook list	—	CLI only
Webhook deliveries	ironflow webhook deliveries --provider stripe	—	CLI only
Test webhook	ironflow webhook test --provider stripe --payload '{...}'	—	CLI only

Recommendation for AI-Assisted Development

Use the CLI as your primary tool. It covers every Ironflow feature except the KV store, overview stats, worker listing, MCP documentation retrieval, and the ironflow_await_reload barrier, is self-documenting via --help, and supports --wait for synchronous feedback loops — which is critical when an AI is iterating on your application.

Supplement with MCP for API contracts and authoring guides, KV store operations, overview stats, worker monitoring, and the reload barrier — these are currently MCP-only.

The key CLI advantage: ironflow emit --wait emits an event and blocks until the triggered run completes, returning the full result. It calls a different server RPC (TriggerSync) than the fire-and-forget path. This gives the AI a tight build-test-fix loop. MCP’s ironflow_emit_event posts to the async endpoint; the AI follows it with ironflow_wait_for_run for each returned run ID.

Example AI Development Loop (CLI)

# AI writes worker code, then tests it:
ironflow emit order.placed --data '{"orderId":"ord-1","total":49.99}' --wait --json

# If something fails, AI inspects:
ironflow run list --status failed --json
ironflow run get <run-id> --json

# AI waits for the projection to catch up, then checks its state:
ironflow projection wait order-stats
ironflow projection get order-stats --json

# AI queries the database directly:
ironflow sql "SELECT * FROM runs WHERE status = 'failed' ORDER BY created_at DESC LIMIT 5" --format json
# --format supports: table (default), json, csv, jsonl