flowctl CLI reference — flowwork docs

flowctl is the REST client for the flowwork engine. Each command maps to one engine operation. Run flowctl <group> <cmd> --help for the full flag list.

Global flags & env

Flag	Env	Default	Meaning
`--server`	`FLOWCTL_SERVER`	`http://localhost:9010/api`	engine base URL (include `/api`)
`-w, --workspace`	`FLOWCTL_WORKSPACE`	`1`	workspace id
`-u, --user`	`FLOWCTL_USER`	`1`	user id
`-o, --output`	—	`table`	`json` or `table`
`-q, --quiet`	—	off	print only the resulting id — great for `$(...)`
`--debug`	—	off	dump HTTP request/response lines to stderr

def — definitions

flowctl def create --file <workflow.js> [--version <v>]   # register; prints definition id
flowctl def get <id>
flowctl def graph <id>                                    # nodes / edges / interactions
flowctl def script <id>                                   # print the JS source
flowctl def list                                          # definitions in the workspace
flowctl def versions <name>                               # all versions of a named workflow
flowctl def active <name>                                 # active version
flowctl def activate <id>
flowctl def delete <id>

run — workflow runs

flowctl run start (--def <id> | --workflow <name>) [--input '<json>' | --input-file <f>] [--channel <id>]
flowctl run status <exec>                                 # status + variables + outcome + result
flowctl run vars <exec>                                   # variables only
flowctl run list [--def <id>]
flowctl run events <exec>                                 # audit events
flowctl run narrative <exec>                              # human-readable timeline
flowctl run cancel <exec>
flowctl run watch <exec> [--interval 2s]                  # poll until terminal

form / signal / webhook — resume a parked run

flowctl form list <exec>
flowctl form get <exec> <formName>                        # schema to know what to submit
flowctl form submit <exec> <formName> --data '<json>'

flowctl signal send <exec> --name <signalName> [--data '<json>']

flowctl webhook list <exec>                               # registered paths
flowctl webhook call <exec> <path> [--payload '<json>']   # leading slash optional

agent — answer agent() prompts

flowctl agent list <exec>
flowctl agent get  <exec> <name>                          # prompt, result_type, context, schema
flowctl agent submit <exec> <name> --type json --result '{"category":"auth"}'
flowctl agent submit <exec> <name> --type text --result 'a plain-text answer'
flowctl agent submit <exec> <name> --error 'could not classify'   # routes to onError

query — read-only introspection

flowctl query list <workflow-id>                          # @query handler names (definition id)
flowctl query run <exec> <queryName>

trigger — manage triggers & start through them

flowctl trigger list
flowctl trigger get <triggerId>
flowctl trigger enable <triggerId> | trigger disable <triggerId>
flowctl trigger config <triggerId> --data '<json>'        # per-workspace override
flowctl trigger webhook-info <triggerId>
flowctl trigger rotate-secret <triggerId>                 # returns the secret once
flowctl trigger start  <api|form> <workflow> <trigger> [--input '<json>']
flowctl trigger schema <api|form> <workflow> <trigger>    # input schema

conn / instance — connections & credentials

flowctl conn list                             # name, description, version, scope
flowctl conn ops <name>                       # operations — no schemas
flowctl conn schema <name> <operation>        # one operation's request + response schemas
flowctl conn manifest <name>                  # full manifest (heavy; rarely needed)

flowctl instance list [--connection <name>]
flowctl instance get    <connection> <instance>           # credentials never returned
flowctl instance create <connection> --name <n> [--credentials '<json>'] [--config '<json>']
flowctl instance update <connection> <instance> [--credentials '<json>']
flowctl instance delete <connection> <instance>

To author a connector() step token-cheaply: conn list → conn ops <name> → conn schema <name> <op> (the exact mapper/combiner shapes) → instance list.

jobs / skill

flowctl jobs list <exec>                      # connector jobs for a run
flowctl jobs get  <exec> <jobId>

flowctl skill install                         # add the authoring skill to Claude Code
flowctl skill install --global | --local | --dir <path>

You normally don't need flowctl init

flowctl init seeds a workspace + user directly in the database. The released binary already auto-seeds the default workspace 1 + user 1 on startup, so you only need init if you want to add additional workspaces or users.

Scripting pattern

DEF=$(flowctl def create --file wf.js -q)
EXEC=$(flowctl run start --def "$DEF" --input '{"x":1}' -q)
flowctl run watch "$EXEC"