CLI Reference

The ironflow CLI is the primary interface for running the server, emitting events, invoking functions, debugging runs, and managing environments.

ironflow [command] [flags]

Global Behavior

Explicit server URL flags override environment variables. Empty environment values are treated as unset.

• All client commands (apikey, audit, capacity, circuit-breaker, dead-letters, debounce, emit, env, event, function, invoke, org, outbox, platform, policy, project, projection, role, run, secret, server, sql, stream, subscribe, tenant, topic, webhook) connect to the server specified by IRONFLOW_SERVER_URL (default: http://localhost:9123)

• a2a and mcp read IRONFLOW_SERVER_URL and IRONFLOW_API_KEY unless --server-url / --api-key are given. inspect --server also reads IRONFLOW_SERVER_URL and otherwise uses http://localhost:9123.

• API key authentication is supported via IRONFLOW_API_KEY when the server has auth enabled. This includes inspect and the WebSocket commands (subscribe, projection watch, stream subscribe).

• The --as-org <org_id> global flag allows platform users to impersonate an organization. Requires platform credentials (via ironflow platform login). Sends the platform JWT and sets the X-Ironflow-Org header on requests. It currently takes effect on the commands that call the REST API (apikey, circuit-breaker, dead-letters, debounce, env, org, outbox, policy, project, role, secret, tenant, and webhook test), on inspect, and on the WebSocket commands. platform subcommands and policy --platform refuse the flag, because they act on the whole instance, not on one organization. capacity sends the platform credentials, and the server ignores the org on its routes. The commands that call the ConnectRPC API (audit, emit, event, function, invoke, projection, run, server, sql, stream, topic, webhook list, webhook deliveries) accept the flag but ignore it.

• The --verbose / -v global flag enables debug-level diagnostic logging on stderr. By default, CLI commands run at warn level (quiet). The serve command defaults to info level so startup messages remain visible. The LOG_LEVEL env var overrides both the flag and defaults.

• --as-org and -v/--verbose are the only persistent flags. Every other flag belongs to one command. --json is common, but each command declares it for itself. --env exists only on apikey create, capacity, circuit-breaker, debounce cancel, dead-letters list, outbox dlq, secret and tenant. There is no global --project flag. The only --project flag is on env create, and projection wait-for-event --projection is a different flag.

• When IRONFLOW_SERVER_URL and IRONFLOW_API_KEY are both unset, the CLI reads the nearest .ironflow/engine.json in the working directory or a parent directory. It takes the server URL, the API key and the environment from that file. A value that you set in IRONFLOW_ENV wins. Set IRONFLOW_NO_DISCOVERY=1 to turn this lookup off. See --discovery-file on ironflow serve.

• Logs are written to stderr; user-facing output (tables, JSON) goes to stdout. Piping output (e.g., ironflow function list --json | jq .) is unaffected by verbose logging.

• Platform commands (ironflow platform *) authenticate using stored platform credentials (JWT token in ~/.config/ironflow/credentials.json) obtained via ironflow platform login. Falls back to IRONFLOW_API_KEY if no platform credentials are found.

• Server and local commands (serve, init, config, validate, conformance, skills, version) run locally and contact no Ironflow server. Operator commands (cloud) connect directly to the Ironflow Cloud control-plane Postgres via IRONFLOW_DATABASE_URL rather than the Ironflow server API.

• ironflow update check contacts the public release mirror, and no other command does. When a response from the server carries a different X-Ironflow-Version than the CLI, the CLI prints one warning on stderr. See ironflow update.

• Exit codes tell the error class, so a script can branch without parsing output:

  Exit	Meaning
  0	Success
  1	Other failure, a run that timed out or paused after exhausting its retries (or failed, except under --json on emit and invoke), or a declined confirmation prompt
  3	Retryable: the engine is unreachable, rate limited, or failed internally. Retry the same command
  4	Invalid input or usage (bad flag, missing argument, rejected value)
  5	Not authenticated, or the API key lacks permission
  6	Not found
  7	Conflict or wrong state (already exists, lost a concurrent write, precondition failed)

  projection wait, projection wait-for-event and projection wait-batch keep their own codes: 1 timeout, 2 error.

• With --json, or with IRONFLOW_OUTPUT=json for any command, an error is one JSON object on stdout: {"error": "...", "code": "not_found", "retryable": false, "hint": "..."}. code is the lowercase ConnectRPC code; optional fields are reason, retry_after (seconds) and hint. Without JSON mode the error goes to stderr as Error: ..., followed by Hint: ... when there is one.

---

Commands

Command	Purpose
ironflow a2a	Expose agents to remote agents over the Agent2Agent (A2A) protocol.
ironflow apikey	Manage API keys for authentication. Create, list, delete, and rotate API keys.
ironflow audit	View and query history inspection (audit trail) records for workflow runs and auth decisions. Uses the ConnectRPC API.
ironflow config	Configuration file management.
ironflow cloud	Operator-only commands for the Ironflow Cloud control plane. They read the control-plane Postgres directly (IRONFLOW_DATABASE_URL) or mint local signing artifacts. They are not for self-hosted users or tenant operators, and no Cloud service runs today.
ironflow capacity	Inspection of the unified capacity/dispatch subsystem (ADR 0037, #1206). Read-only views over the database-backed capacity tables. Requires platform credentials (any platform principal — platform_admin, operator, or viewer; the gate is “is-platform”, not a specific role) — set IRONFLOW_API_KEY to a ifplatform_ key or authenticate via ironflow platform login. Regular tenant keys return 403.
ironflow circuit-breaker	Manage circuit breakers that protect push endpoints from cascading failures. Circuit breaker state is persisted in the database and is cluster-consistent (consulted at dispatch reservation time).
ironflow conformance	Check your own handler against an Ironflow wire contract. Contacts no server.
ironflow dead-letters	List stored dead-letter rows for one explicit environment, with optional source filtering and base64 payloads in JSON output.
ironflow debounce	Inspect and cancel pending debounce entries for functions that collapse rapid-fire events into a single invocation. See the debounce how-to for background.
ironflow emit	Emit a named event to the server. If any registered functions have triggers matching the event name, runs will be created for them.
ironflow env	Manage environments.
ironflow event	Manage event schemas, test upcasters, and redact events.
ironflow function	List and inspect registered functions.
ironflow init	Create a new Ironflow project from a template.
ironflow inspect	Inspect a workflow run with the TUI debugger.
ironflow invoke	Directly invoke a function by ID.
ironflow mcp	Start the Model Context Protocol (MCP) server for AI assistant integration.
ironflow org	Manage organizations. Create, list, get, and delete organizations.
ironflow outbox	Inspect and manage the transactional outbox (issue #487). Today the only exposed subtree is dlq — operator tooling for the dead-letter table when a publish has failed past its retry budget. See the outbox explanation for background and triage flow.
ironflow platform	Manage the Ironflow platform: users, tenants, roles, and audit log.
ironflow policy	Manage the Rego policy set of an organization: pull, push, validate, dry-run, versions, rollback and the platform force-monitor break-glass.
ironflow project	Manage projects. Projects group related environments within an organization (e.g., a microservice or team boundary). The resource hierarchy is Organization → Project → Environment.
ironflow projection	Manage projections: create, list, inspect, pause, resume, delete, rebuild, and wait for catch-up.
ironflow role	Manage custom roles for authorization.
ironflow run	List and inspect workflow runs, and control them: cancel, delete, prune, redact, pause, inject step output, and resume.
ironflow secret	Manage encrypted secrets. Secrets are environment-scoped and write-only — values can be set but are never returned by the CLI or API.
ironflow skills	Manage the Ironflow AI skills bundled with this binary. The skills are compiled into the binary, so they match its version exactly. Write them to disk with ironflow skills sync, then wire your coding agent with ironflow skills doctor.
ironflow serve	Start the Ironflow server with embedded NATS JetStream, database, and web dashboard.
ironflow server	Server management commands.
ironflow sql	Execute a read-only SQL query against the Ironflow database.
ironflow stream	Manage entity streams for event sourcing.
ironflow subscribe	Subscribe to real-time events via WebSocket.
ironflow tenant	Provision and list tenant organizations. Tenants provide multi-tenancy by creating an organization, built-in roles, a default project and environment, and an admin API key.
ironflow topic	Manage developer pub/sub topics: list topics, view statistics, and publish messages.
ironflow update	Check whether a newer Ironflow release is available.
ironflow validate	Validate an ironflow.yaml configuration file without starting the server. Checks syntax, schema, environment variable references, and kind-specific rules.
ironflow version	Print version and build information.
ironflow webhook	Manage webhook sources and deliveries.

Environment Variables

These are the environment variables read by the CLI itself. For server-side configuration (database, NATS, dashboard auth, etc.), see Configuration. Command-specific variables are documented on their own pages: IRONFLOW_SIGNING_KEY on conformance, NATS_URL / NATS_CREDS_FILE on projection, and IRONFLOW_MASTER_KEY_B64 / IRONFLOW_CAP_TOKEN_PRIVATE_KEY_B64 / IRONFLOW_DATABASE_URL on cloud.

Variable	Default	Description
IRONFLOW_SERVER_URL	http://localhost:9123	Server URL for all client commands
IRONFLOW_API_KEY	(none)	API key sent as Authorization: Bearer header for auth
IRONFLOW_ENV	(none)	Environment ID for scoping queries and operations (for example env_default)
IRONFLOW_CONFIG_DIR	~/.config/ironflow	Directory for storing platform credentials (credentials.json)
IRONFLOW_OUTPUT	(none)	json makes every command print errors as a JSON object on stdout
IRONFLOW_NO_DISCOVERY	(none)	1 turns off the .ironflow/engine.json lookup
IRONFLOW_MCP_BEARER_TOKEN	(none)	Required by ironflow mcp --transport streamable-http; ignored on stdio
IRONFLOW_MCP_EXIT_ON_STDIN_CLOSE	(none)	1 makes ironflow mcp --transport streamable-http exit when its stdin closes
IRONFLOW_TERMINAL_BRIDGE_TOKEN	(none)	Bearer token for the Ironflow Desktop terminal bridge; needed by ironflow mcp --terminal-bridge-url
IRONFLOW_A2A_BEARER_TOKEN	(none)	Required by ironflow a2a; remote callers send it as a bearer token
LOG_LEVEL	warn (info for serve)	Log level: trace, debug, info, warn, error, fatal
LOG_FORMAT	(none)	text switches serve from JSON logs to human-readable console output