CLI & Agent Skill

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 for your OS

macOS

Open Terminal and run this in zsh or bash. The installer supports Intel and Apple Silicon Macs, with no dependencies:

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The CLI is installed in ~/.local/bin. Add the export PATH line to ~/.zshrc (or ~/.bash_profile for bash) so new terminals can find it too.

Linux

Open a bash-compatible terminal and run. The installer supports x86_64 and arm64 Linux:

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The CLI is installed in ~/.local/bin. Add the export PATH line to your shell startup file (for example, ~/.bashrc) so new terminals can find it too.

Windows

PowerShell

Install Deno 2+ if you don’t already have it:

winget install --id DenoLand.Deno --exact

Close and reopen PowerShell, then install QuickFlo:

deno install --global --force --name quickflo --allow-net --allow-read --allow-env --allow-write jsr:@quickflo/cli
$env:Path = "$env:USERPROFILE\.deno\bin;$env:Path"

The CLI is installed in %USERPROFILE%\.deno\bin by default. Add that directory to your user Path in Windows Environment Variables so new terminals and coding agents can find it. If Deno reports a custom installation directory, use that path instead.

Already using Git Bash? Install the Windows binary directly

Run this in Git Bash on Windows x64:

curl -fsSL https://cdn.quickflo.app/packages/cli/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

This downloads quickflo.exe without Deno. Add the export PATH line to ~/.bashrc for future Git Bash sessions. To use the binary in PowerShell or a coding agent too, add %USERPROFILE%\.local\bin to your Windows user Path. The curl ... | sh command runs in Git Bash, not PowerShell or Command Prompt.

2. Sign in

In the QuickFlo web app, open Settings → Access Tokens → New token. Copy the token, then paste it when prompted:

quickflo auth login

3. Use the CLI

These commands work in any of the shells above:

quickflo workflows list
quickflo workflows pull -d ./workflows
quickflo workflows push -d ./workflows

4. Install the agent skill (optional)

Choose your coding agent. Installs are global by default, so the skill is available across projects for your user account. These commands work on macOS, Linux, and Windows:

Cursor

quickflo skill install cursor

Codex

quickflo skill install codex

Claude Code

quickflo skill install claude

Shared skill directory

quickflo skill install shared

The shared option installs to ~/.agents/skills/quickflo for agents that support the shared skill directory convention.

In Codex, Claude Code, Cursor, or your agent harness of choice, use quickflo in Agent chat:

$quickflo figure out what happened on the last few runs of workflow activity-sync

Global, project, and custom destinations

quickflo skill install cursor automatically writes to ~/.cursor/skills/quickflo on macOS and Linux, or C:\Users\<username>\.cursor\skills\quickflo\ on Windows. You don’t need to specify the path.

Codex and shared installs go to ~/.agents/skills/quickflo; Claude Code installs to ~/.claude/skills/quickflo. You can make the global default explicit with --scope global; --scope user is an alias for global.

To install for one project, run from that project’s directory:

Install for the current project

quickflo skill install shared --scope project

This writes to .agents/skills/quickflo under the current directory. Use cursor --scope project for .cursor/skills/quickflo, or claude --scope project for .claude/skills/quickflo.

To choose a custom destination for either scope, pass the complete skill directory as the final argument. For example, in Windows PowerShell:

quickflo skill install cursor "$env:USERPROFILE\.cursor\skills\quickflo"

In macOS or Linux:

quickflo skill install cursor "$HOME/.cursor/skills/quickflo"

Each skill directory contains SKILL.md plus the workflow and dashboard guides. See the Cursor skill locations and Codex skill locations.

The no-argument quickflo skill install command keeps the existing Claude Code destination for compatibility.

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

Install

Pre-built binary

Use this in a macOS or Linux shell, or Git Bash on Windows. For native PowerShell, follow the Windows tab in Quick Start.

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

Drops quickflo (or quickflo.exe on Windows) in ~/.local/bin. Detects your OS + arch automatically. Supports macOS (Intel and Apple Silicon), Linux (x86_64 and arm64), and Windows (x86_64). Make sure the installation directory is on your PATH.

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+)

Run this as one line in bash, zsh, or PowerShell:

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

Drops it in ~/.deno/bin (%USERPROFILE%\.deno\bin on Windows) by default — 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 cursor     # ~/.cursor/skills/quickflo
quickflo skill install codex      # ~/.agents/skills/quickflo
quickflo skill install claude     # ~/.claude/skills/quickflo (also the default)
quickflo skill install shared     # ~/.agents/skills/quickflo (shared skill directory)
quickflo skill install agents     # operating guide → ./AGENTS.md
quickflo skill install mcp        # print the MCP host-config snippet

Global is the default, under your home directory. Pass --scope project to install under the current working directory instead:

quickflo skill install shared --scope project

Skill target	Global (default)	Project (--scope project)
cursor	~/.cursor/skills/quickflo/	.cursor/skills/quickflo/
codex	~/.agents/skills/quickflo/	.agents/skills/quickflo/
claude (default)	~/.claude/skills/quickflo/	.claude/skills/quickflo/
shared	~/.agents/skills/quickflo/	.agents/skills/quickflo/

All skill targets write SKILL.md and both authoring guides, which agents load on demand. shared writes the same standard skill as codex, for agents that discover .agents/skills. --scope global explicitly selects the default; --scope user is an alias. A final directory argument overrides the destination for either scope.

The agents target exports the operating guide to ./AGENTS.md as always-on instructions; a final file argument overrides that path. The mcp target prints host configuration. These two exports do not accept --scope.

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.

Note

Tokens are bound to the org they were minted in, so -o/QF_ORG is not required on most commands. The active profile already knows the org.

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