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

Quick Comparison

	CLI (via Bash)	MCP (via tools)
Total operations	~80+	27+ (static)
Coverage	100% of Ironflow features	~42% static (+ 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
Shell escaping	JSON in bash can be tricky	Native JSON parameters
Sync operations	`--wait` flag blocks until complete	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`
Invoke + wait	`ironflow invoke ... --timeout 60s`	—	CLI only
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 failed run	`ironflow run resume <run-id>`	`ironflow_retry_run`	Resumes from last successful step
Pause run	`ironflow run pause <run-id>`	—	CLI only
Resume paused run	`ironflow run resume <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

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`	—	CLI only
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

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)

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`	—	CLI only
Reset circuit breaker	`ironflow circuit-breaker reset <key>`	—	CLI only

Outbox

Operation	CLI	MCP	Notes
List dead-letter entries	`ironflow outbox dlq list`	—	CLI only
Requeue dead-letter entry	`ironflow outbox dlq requeue <eventID>`	—	CLI only
Discard dead-letter entry	`ironflow outbox dlq discard <eventID>`	—	CLI only

RBAC & Policies

Operation	CLI	MCP	Notes
List roles	`ironflow role list`	—	CLI only
Get role	`ironflow role get <role-id>`	—	CLI only
List policies	`ironflow policy list`	—	CLI only
Get policy	`ironflow policy get <policy-id>`	—	CLI only
Create/update policy	`ironflow policy put ...`	—	CLI only
Delete policy	`ironflow policy delete <policy-id>`	—	CLI only
Lint policy	`ironflow policy lint ...`	—	CLI only

Organizations & Tenants

Operation	CLI	MCP	Notes
List organizations	`ironflow org list`	—	CLI only
Get organization	`ironflow org get <org-id>`	—	CLI only
List tenants	`ironflow tenant list`	—	CLI only
Get tenant	`ironflow tenant get <tenant-id>`	—	CLI only

Other CLI Commands

Operation	CLI	MCP	Notes
Initialize project	`ironflow init`	—	CLI only
Validate config	`ironflow validate`	—	CLI only
Show version	`ironflow version`	—	CLI only
List debounces	`ironflow debounce list`	—	CLI only

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 100% of Ironflow’s features, 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. This gives the AI a tight build-test-fix loop. MCP’s ironflow_emit_event is fire-and-forget; 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 checks projection state:
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