CLI

The blitflow CLI wraps the same contract operations for terminal use — handy for trying nodes, running YAML-defined workflows, and scripting.

Install

The CLI ships on npm as blitflow — a single self-contained bundle, no runtime dependencies. Requires Node.js 20+.

npm install -g blitflow
# or run it without installing:
bunx blitflow --help
npx blitflow --help

First use

# opens a code to approve in the browser; the token is saved locally
blitflow login

# run a single node — progress on stderr, results on stdout
blitflow node rd-fast -i prompt="a brass key" --max-cost 0.10

Commands

blitflow login                       Sign in via the browser (OAuth device flow)
blitflow logout                      Remove the saved token
blitflow whoami                      Show the signed-in user
blitflow nodes [query]               List or search the node palette
blitflow node <id> [--input k=v]...  Run a single node (no workflow)
blitflow run <file.yaml|ref> [--input k=v]...  Run a workflow

run takes either a local YAML file or a reference to a published workflow: the published <org-slug>/<workflow-slug> address (preferred, e.g. acme/sprite-pack@1.2.0) or the workflow's internal UUID, optionally @<version> — see Versioning. The CLI disambiguates by a simple rule: if the argument exists as a file on disk it is a file (a directory does not count); otherwise, anything that parses as a workflow ref is a ref.

Option	Description
`-i, --input k=v`	Input value (repeatable). Use `@<url>` for a file/image input
`--max-cost N`	Cap the run's spend in USD
`--json`	Machine-readable output on stdout
`--url U`	API base URL (else `BLITFLOW_URL`, else saved, else default)

Examples

# sign in once — saves a session token to ~/.blitflow/config.json
blitflow login

# explore the palette
blitflow nodes sprite

# run one node
blitflow node rd-fast \
  -i prompt="a brass key" -i removeBg=true -i seed=7 \
  --max-cost 0.10

# run a published workflow by its address
blitflow run acme/sprite-pack@2.1.0 \
  -i prompt="isometric stone tower" --max-cost 0.25

# the internal UUID form works too
blitflow run 8f61e451-40a7-4f65-8fa9-69704576b6d4@2.1.0 -i prompt="a brass key"

# run a local YAML workflow definition
blitflow run flow.yaml -i photo=@https://example.com/tower.jpg

Inputs

Plain values are scalars — numbers and booleans are coerced (seed=7, removeBg=true).
For run, values become inline artifacts typed by the workflow's declared input connector.
@https://…/x.png becomes a ref artifact, kind inferred from the file extension.

YAML workflow files use the same shape as the JSON workflow definition.

Configuration

The token from blitflow login lives in ~/.blitflow/config.json. For CI or headless use, set BLITFLOW_TOKEN (a personal access token) instead of logging in; BLITFLOW_URL overrides the API base URL.