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

Sign in once, then run something:

# 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"

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
blitflow mcp                         Serve the BlitFlow MCP server over stdio

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.

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

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

# 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.

Text feedback

Create a minimized JSON report with a stable submissionKey UUID, source (cli), category (bug or feedback) and comment (1–8,000 characters). Optional reproduction, expected and actual fields each allow 2,000 characters.

blitflow feedback --file report.json --org acme --dry-run --json
blitflow feedback --file report.json --org acme --json
cat report.json | blitflow feedback --file - --org acme --json

Dry-run prints a sanitized preview without signing in or submitting. Review it before submitting. File/stdin input is limited to 64 KiB and avoids putting the report text in shell history. Reuse the same submission key when retrying; the server returns the original { id, createdAt } receipt without changing its body. All member roles may submit. Admission allows ten new reports per rolling minute per principal, across organizations. Reports become eligible for daily deletion after ninety days. There is no report-read API or public feed.

Never reveal sensitive data in feedback. Anonymize the report before submitting: replace names, emails, organization/customer identifiers and private paths with neutral placeholders. Remove API keys, tokens, passwords, cookies, authorization headers, environment variables, private prompts/assets and customer data. Include only the minimum reproduction steps and sanitized error details. Do not attach transcripts, files, screenshots or raw logs automatically. If a report cannot be made safe, omit the sensitive detail and describe the failure generally.

Known-pattern redaction helps minimize reports; it cannot recognize every private fact.