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

All client commands (apikey, audit, capacity, circuit-breaker, debounce, emit, env, event, function, inspect, invoke, mcp, 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)
API key authentication is supported via IRONFLOW_API_KEY when the server has auth enabled
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.
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.
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, deploy, provision, skills, version) run locally and contact no Ironflow server. Operator commands (cloud) connect directly to the meta-cluster Postgres via IRONFLOW_DATABASE_URL rather than the Ironflow server API.
Exit code 0 indicates success; 1 indicates an error

Commands

Command	Purpose
`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`	Ironflow Cloud operator commands (meta-cluster). These commands read from the meta-cluster Postgres directly (`IRONFLOW_DATABASE_URL`) or mint local signing artifacts. They are intended for the founder running on the meta box — they are not exposed to tenant operators.
`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 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 deploy`	Deploy Ironflow to a Kubernetes cluster using Helm templates, or to a single VPS over SSH.
`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 and test upcasters.
`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 authorization policies.
`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 provision`	Provision infrastructure for Ironflow (Kubernetes cluster creation).
`ironflow role`	Manage custom roles for enterprise authorization.
`ironflow run`	List and inspect workflow runs, and control them: cancel, 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 atomically creating an organization, built-in roles, and a default environment.
`ironflow topic`	Manage developer pub/sub topics: list topics, view statistics, and publish messages.
`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: HCLOUD_TOKEN on provision, HETZNER_S3_ENDPOINT / HETZNER_S3_BUCKET on deploy, 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`	`default`	Environment name for scoping queries and operations
`IRONFLOW_CONFIG_DIR`	`~/.config/ironflow`	Directory for storing platform credentials (`credentials.json`)
`IRONFLOW_MCP_BEARER_TOKEN`	(none)	Required by `ironflow mcp --transport streamable-http`; ignored on stdio
`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