axiom invoke#

Invoke a published node directly and print its raw JSON response

Invoke a published node directly — the same endpoint "axiom push" prints after a successful push — and print its raw JSON response body to stdout.

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

--input '<json>'      inline JSON, e.g. --input '{"text":"hello world"}'
--input-file <path>   read JSON from a file
piped stdin            echo '{"text":"hello world"}' | axiom invoke ...

When @version is omitted, the most recently published version is used.

Input size: the request body is capped at 16 MiB (the platform run-payload cap). Larger inputs are rejected before the node runs. Binary inputs (e.g. an image for a resize/convert node) are base64-encoded inside the JSON, which inflates them by ~33%, so a raw file up to ~12 MiB fits. A typical phone photo (1–5 MB) is well within the limit and does not need to be pre-shrunk.

The response body is printed to stdout exactly as returned, so it pipes cleanly into jq; all diagnostics and status messages go to stderr. Exits non-zero on a node error or non-2xx HTTP status, 0 on success. Requires a prior "axiom login".

Pipeline (streaming) nodes: a node declared "type: pipeline" emits a SEQUENCE of output frames, and the platform answers this endpoint with Server-Sent Events. Each frame is printed on its own line as it arrives — so a token relay prints tokens as they are produced — and stdout stays one JSON object per line for jq. Unary nodes are unchanged: one JSON body, verbatim.

Streaming INPUT (pipeline nodes only):

--input-stream <path>   send NDJSON — one JSON object per LINE, one node
--input-stream -        input frame per line — read from a file or stdin

Each line is sent to the node as its own input frame AS IT IS READ, so the node starts producing output before the input has ended and the input never has to fit in memory (or end at all). Limits: 16 MiB per frame, 64 MiB and 100000 frames per stream, and 5 minutes of wall clock — the platform's node ceiling. --timeout defaults to 300s in this mode; pass it explicitly to override. Blank lines are skipped. A frame the node rejects ends the stream with an error naming the offending frame index.

Under the hood this drives three half-duplex requests — create the stream, attach its output channel, then upload — because one request cannot carry a live body up and a live response down without the upload being cut short. The frames sent are reconciled against the count the platform accepted, and a mismatch FAILS the invoke rather than printing a clean run over a lossy one.

Note that true INCREMENTAL consumption depends on the node's language: Go, Python and TypeScript nodes see each frame as it arrives; Rust buffers the whole stream before running; Java and C# begin only after the input ends. Every language receives every frame — the difference is when.

LIVE MODE (pipeline nodes only):

--live <path>           full-duplex session over ONE WebSocket: frames go up
--live -                and come down at the same time on the same connection

--input-stream and --live both stream frames in; they differ in what they promise.

--input-stream is DURABLE BULK INGESTION. Three half-duplex requests, an
output channel that replays from offset, and a frame count reconciled against
what the platform accepted. Use it to push a large or log-shaped stream
through a node and know nothing was lost.

--live is an INTERACTIVE SESSION and is EXPLICITLY EPHEMERAL: it is pinned to
one ingress pod, writes NO durable execution row, and cannot be replayed. If
the pod restarts the session dies and the only recovery is to reconnect and
re-send. Nothing is written down — do not look for it in "axiom executions".
Use it when the value is in the round trip (a token relay, a live tail, an
interactive dialogue) rather than in the record.

Live limits: 16 MiB per frame, 64 MiB of OUTPUT per session, 100000 input frames, and the same 5-minute node ceiling. A session whose client stops reading is CLOSED rather than buffered — the platform will not hold unbounded output for a slow consumer, and says so with a close reason.

axiom invoke nadia/summarizer/Summarize --input '{"text":"hello world"}'
tail -f events.ndjson | axiom invoke me/tools/StreamRecords --input-stream -
axiom invoke me/tools/Chat --live -   # type JSON lines, see replies arrive

Usage#

axiom invoke <handle>/<package>/<node>[@version] [flags]

Flags#

See also#

• axiom — Axiom CLI — build and push node packages