axiom flow run#

Invoke a compiled flow and print its result

Invoke a compiled flow and wait for the result.

Name the flow — "<handle>/<flow-name>", optionally "@<version>" — or give the artifact id printed by "axiom flow compile". PREFER THE NAME: it always resolves to the flow's CURRENT published graph, while an artifact id names one published version and goes stale the moment the author republishes.

Provide the start node's input JSON with exactly one of:

-d, --data '<json>'   inline JSON, e.g. -d '{"value":"hello"}'
--input-file <path>   read JSON from a file
piped stdin           echo '{"value":"hello"}' | axiom flow run 01J…

The ingress transcodes it to protobuf automatically, and the result is decoded back to JSON. Requires a prior "axiom login".

Streaming: a flow compiled with "pipeline_mode: true" emits a STREAM of output frames, not one result. Pass --stream to receive them as they are produced — one JSON object per line on stdout, printed the moment each frame arrives. Without --stream a pipeline flow is sent to the unary endpoint, which returns a single aggregated result and DISCARDS every later frame; the command says so loudly rather than letting a truncated result read as the flow's output. With --stream, --timeout bounds how long the server keeps the stream open; if it elapses the run is still executing and the command says so and exits 0, just as it does without --stream.

Waiting: --timeout (default 60s) is how long the CLI waits for the SYNCHRONOUS answer, NOT a cap on the flow. If it elapses the run is still executing, so the command keeps POLLING the execution for up to --poll-timeout seconds (default 600) and then reports what actually happened:

COMPLETED                   the output, exit 0
FAILED / CANCELLED          the platform's error message, exit non-zero
PAUSED / WAITING_ON_GATE    parked for a human, how to resume it, exit 0
still running at the end    "still running" + "axiom executions get <id>",
                            exit 0 — never reported as a failure

The same polling recovers a run whose invoke response is LOST (client timeout, dropped connection): every invoke carries a unique Idempotency-Key, so the CLI re-asks the ingress which execution its request created and follows that, instead of claiming "context deadline exceeded" about a run that is fine. Pass --poll-timeout 0 to switch polling off. A COLD flow is slow on its first run because each node's sidecar scales from zero, so a multi-node flow's first run often needs a longer --timeout; the next run is typically much faster.

Machine-readable output: with --json, stdout carries EXACTLY ONE JSON object on every path — success, polled terminal state, still-running, pause, or error — and every diagnostic goes to stderr. (With --stream it is one JSON object per line: JSONL.) A polled result is marked "result_source":"durable_record" and its output is camelCase protojson, unlike the snake_case synchronous result.

Input size: the request body is capped at 16 MiB (the platform run-payload cap). Prefer --input-file or stdin for large documents — a single shell argument is limited to ~128 KiB by the OS (MAX_ARG_STRLEN), so -d "$(cat big.json)" fails with "Argument list too long" well below the platform cap.

axiom flow run nadia/cron-explainer -d '{"cron":"0 9 * * 1"}'
axiom flow run nadia/cron-explainer@1.2.0 -d '{"cron":"0 9 * * 1"}'
axiom flow run 01J… -d '{"value":"hello"}'
axiom flow run 01J… --input-file page.json
jq -c . page.json | axiom flow run 01J…
axiom flow run 01J… --stream -d '{"text":"hello"}'   # pipeline flow

Usage#

axiom flow run <flow-name|artifact-id> [flags]

Flags#

See also#

• axiom flow — Author and compile flows (graphs of published nodes)