CLI

Almost everything you can do in the QuickFlo web app, you can do from the terminal, and so can your agent: build, run, and debug workflows, read execution traces, and manage your org. The distance between describing what you want and watching it run gets very short.

Quick Start

# 1. Install
curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh

# 2. Mint an access token in the QuickFlo web UI:
#    Settings → Access Tokens → New token
#
# 3. Sign in by pasting that token
quickflo auth login

# 4. Use it
quickflo workflows list
quickflo workflows pull -d ./workflows
quickflo workflows push -d ./workflows

# 5. (Optional) Install the agent skill so Claude can drive the CLI for you
quickflo skill install

With the skill installed, point your agent at the CLI in plain English:

claude /quickflo figure out what happened on the last few runs of workflow list-sync-webhook

That’s the whole flow. Everything below is detail.

Install

Pre-built binary (recommended)

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh

Drops quickflo in ~/.local/bin. Detects your OS + arch automatically. Supports macOS (Intel and Apple Silicon), Linux (x86_64 and arm64), and Windows (x86_64).

Pin a version:

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh -s v1.0.2

Install elsewhere:

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | INSTALL_DIR=/usr/local/bin sh

Via JSR (requires Deno 2+)

deno install --global --force --name quickflo \
  --allow-net --allow-read --allow-env --allow-write \
  jsr:@quickflo/cli

Drops it in ~/.deno/bin — make sure that’s on your PATH.

Agent skill

Install the QuickFlo agent skill (the operating guide and workflow-authoring conventions for driving this CLI) into any agent harness. The guides ship embedded in the CLI, so installs need no repo checkout and no network:

quickflo skill install                            # Claude skill → ~/.claude/skills/quickflo
quickflo skill install agents ~/.codex/AGENTS.md  # Codex / agents.md
quickflo skill install mcp                        # print the MCP host-config snippet

Harness	What it writes	Loading
`claude` (default)	`SKILL.md` + `building-workflows.md` in `~/.claude/skills/quickflo/`	lazy (description-gated)
`agents`	`AGENTS.md` (Codex: `~/.codex/AGENTS.md`, or repo root)	eager (always-on)
`mcp`	prints the MCP host config	tools + on-demand resources

For an MCP host (Claude Code, Claude Desktop, Cursor), prefer quickflo mcp — it runs a stdio server that serves these same guides as quickflo:// resources, so you get the how-to plus typed tools with no skill file.

Auth

The CLI authenticates with Personal Access Tokens, organized into named profiles so you can keep tokens for multiple orgs or deployments and switch between them with one command.

Mint a token in the web UI at Settings → Access Tokens, then:

quickflo auth login          # paste token, saves under a profile named after the org
quickflo auth list           # show saved profiles, * marks active
quickflo auth use <name>     # switch active profile
quickflo auth status         # verify the active token still works
quickflo auth logout         # delete the active profile

Profiles live at ~/.config/quickflo/credentials.json (mode 0600). Each profile bundles its api URL, token, and cached org info, so switching profiles switches everything in one move.

Env-based auth (for CI)

export QF_TOKEN=qfp_…    # bypasses profiles entirely
quickflo workflows list

Resolution priority: QF_TOKEN env → QF_PROFILE env → active profile → fail with hint.

Common commands

Workflows

quickflo workflows list                          # table view
quickflo workflows list -j | jq                  # JSON for scripting
quickflo workflows list --where name:re:'^Free'  # regex filter

quickflo workflows get abcd                      # auto-detect (UUID, SUID, or name)
quickflo workflows get abcd > my-workflow.json   # save pushable shape

quickflo workflows push -d ./workflows           # bulk upsert from a directory
quickflo workflows push -d ./workflows -w        # + create webhook triggers
quickflo workflows push --dry-run -d ./workflows

quickflo workflows pull -d ./workflows           # download all to ./workflows
quickflo workflows pull -n 'Free Tool' -d ./free # filter by name substring

Validate, run, observe

The author → run → observe → fix loop, without leaving the terminal.

workflows validate runs locally with zero network calls by default — instant feedback for AI agents and CI, no token needed. --strict adds a server-side schema check. Exits 0 on success, 3 on validation failure.

quickflo workflows validate ./my-wf.json         # local, no network
cat ./my-wf.json | quickflo workflows validate --from-stdin
quickflo workflows validate ./my-wf.json --strict -o abcd  # + server schema check
quickflo workflows validate ./my-wf.json -j      # JSON for CI

Run a workflow manually and inspect what happened:

quickflo workflows run my-wf --input '{"x":1}' --mode sync   # wait, print step table + output
quickflo workflows run my-wf --input-file ./payload.json --mode async  # queue, print executionId
quickflo workflows run my-wf --env staging --input '{}'      # pick the env for variable resolution
quickflo workflows run my-wf --input '{}' --timeout 30       # CLI-side timeout (sync); exits 124
quickflo workflows run my-wf --input '{}' \
  --save-trace ./trace.json --save-steps-to ./steps/         # persist trace + one file per step

quickflo workflows executions list --status failed --since 1h  # find recent failures
quickflo workflows executions get <execution-id>               # full trace metadata + step paths
quickflo workflows executions logs <execution-id> --step fetchUsers  # one step's output
quickflo workflows executions logs <execution-id> --full --show-secrets
quickflo workflows executions download <execution-id> --out ./trace.json
quickflo workflows executions tail <execution-id>              # follow a running execution
quickflo workflows executions replay <execution-id>            # re-run with the same input

Discover step types while authoring:

quickflo workflows steps list             # table of every step type
quickflo workflows steps get http-request # input/output JSON schemas + example

Packages

quickflo packages list                           # what your org has published
quickflo packages list --installed               # what's installed into your org

quickflo packages install @acme/onboarding       # canonical address
quickflo packages install qfi_AbC123…            # unlisted-install token
quickflo packages install ./pkg.qfpkg.zip        # local file

quickflo packages publish my-pkg \
  --version 1.0.0 \
  --root workflow:abc123 \
  --readme ./README.md

Other resources

The CLI manages the rest of your org’s resources with the same list / get / create / pull / push shape. Run quickflo <noun> --help for the full flag set:

quickflo connections list      # saved credentials; also: types, create, update, pull/push, test
quickflo environments list     # per-env variable bags; also: vars, set/unset, pull/push
quickflo triggers list         # webhook/schedule/event/form entry points; org-wide by default
quickflo data-stores list <table>  # JSONB KV per org; also: tables, get/set, import/export

Filter DSL

--where <field>:<op>:<value> is available on every list and pull command. Operators: eq, ne, re (regex), gt, gte, lt, lte, in, nin, like, ilike.

quickflo workflows list --where name:re:Free --where createdAt:gt:2026-01-01
quickflo packages list --where visibility:eq:public

MCP server

quickflo mcp runs a stdio MCP server so an AI agent (Claude Code, Claude Desktop, Cursor) can build workflows with typed tools:

list_steps, get_step_schema, list_connections — introspect the catalog
validate_workflow — the compiler loop (undefined/forward references, unknown filters/fields, missing connections); run after every edit
save_workflow_draft — create or update a workflow as a draft (no triggers, no execution; the server validates on save)

It authenticates with your active CLI profile (quickflo auth login first) and is a thin client — all validation lives server-side. Add it to your MCP host config:

{
  "mcpServers": {
    "quickflo": {
      "command": "quickflo",
      "args": ["mcp"],
      "env": { "QF_ORG": "abcd" }
    }
  }
}

Set QF_ORG to your org, or pass org per tool call.

Pipe-friendly output

Stdout is the payload; diagnostics go to stderr. Redirect freely:

quickflo workflows get abcd > workflow.json
quickflo workflows list -j | jq '.[].name'

Non-interactive contract

Built so scripts and agents can depend on stable behavior:

Auto-yes on confirm prompts when stdin is not a TTY (matches gh, npm). Pass --yes explicitly in scripts to make intent visible.
-j/--json on every list/get/inspect command — JSON payload to stdout, progress to stderr.
--quiet suppresses progress; errors still print.
JSON error envelope when -j is passed: errors land on stderr as {"error":{"code":"…","message":"…","status":…}}.
Stable exit codes: 0 ok, 1 user error, 2 server error, 3 validation, 124 timeout, 130 interrupted.

Help

quickflo --help
quickflo workflows --help
quickflo workflows push --help