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)

Both hit the same underlying API. The difference is coverage, output format, and interaction style. In addition to the static MCP tools listed below, 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. (Pass --static-only to exclude them.)

MCP is read-only by default

ironflow mcp registers 23 read-only tools. The 11 write tools — ironflow_emit_event, ironflow_invoke_function, ironflow_append_entity_event, ironflow_kv_put, ironflow_secret_set, ironflow_cancel_run, ironflow_resume_run, ironflow_rebuild_projection, ironflow_outbox_dlq_requeue, ironflow_outbox_dlq_discard, ironflow_circuit_breaker_reset — 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 three operator read verbs — ironflow_outbox_dlq_list, ironflow_circuit_breaker_list, ironflow_rebuild_projection_status — are deliberately in the read-only set, so an agent without write access can still see why dispatch is blocked or delivery is failing.

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	37 top-level commands (ironflow --help)	23 read-only, 34 with --allow-writes, 35 with --evidence-file too
Coverage	Everything except KV, overview stats, and worker listing	A subset, including 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	Fire-and-forget only
Recommendation	Primary tool for development	Supplement for KV/overview

Core Operations

Operation	CLI	MCP	Notes
Emit event	ironflow emit order.placed --data '{...}'	ironflow_emit_event
Emit + wait for result	ironflow emit ... --wait	—	CLI only — critical for test loops
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 is fire-and-forget
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	—	CLI only
Filter runs by function	ironflow run list --function my-func	—	CLI only
Get run details	ironflow run get <run-id>	ironflow_get_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
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
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; the MCP tool exposes no dry_run because the server does not honor it
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
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

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
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
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

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

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 for confirmation; the MCP tool cannot

RBAC & Policies

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
Attach/detach policy on a role	ironflow role assign-policy ... / ironflow role remove-policy ...	—	CLI only
List policies	ironflow policy list	—	CLI only
Get policy	ironflow policy get <policy-id>	—	CLI only
Create/update policy	ironflow policy create ... / ironflow policy update ...	—	CLI only
Delete policy	ironflow policy delete <policy-id>	—	CLI only
Test/dry-run policy	ironflow policy test ...	—	CLI only
Policy versions / rollback	ironflow policy versions list ... / ironflow policy rollback ...	—	CLI only
Policy templates	ironflow policy template list / ironflow policy template install ...	—	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
Ops / infra	ironflow deploy, provision, platform, cloud	—	CLI only — cluster and tenant 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, and worker listing, 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 KV store operations, overview stats, and worker monitoring — 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 would need to poll ironflow_list_runs to check if the run completed.

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