CLI

The Flow command-line interface (CLI) (flow) is a command-line client for the same REST API documented in API Reference. Ask your Flow administrator how to get the CLI for your organization. Authenticate with API keys from Settings → API & MCP Access at https://app.letsflow.ai. Global options on most commands:

Flag	Purpose
`--api-base-url <url>`	Flow API host
`--output text\|json`	Human table or JSON envelope
`-v, --verbose`	Include IDs, links, and request metadata
`--auth-principal-id`	Development and test principal header
`--auth-org-id`, `--auth-team-id`	Organization and team for the request

Machine authentication uses an API key. The --auth-principal-id flag is for development and test environments. It sends the X-Flow-Dev-Principal-Id header, and the CLI omits it when an API key is present. The --auth-org-id and --auth-team-id flags work with an API key. Flow uses them to choose and check the organization and team.

First catalog request from the CLI

Configure API access.

Create an API key under Settings → API & MCP Access or use credentials from your administrator. Use https://app.letsflow.ai/v1 as the API base URL in the examples below.

List catalog items.

flow catalog list --api-base-url <api-base-url>

Inspect request schema.

flow catalog schema <catalog-item-id> --api-base-url <api-base-url>

Get the form reference.

The default text output does not include form_ref. Request JSON output and extract it:

flow catalog schema <catalog-item-id> --api-base-url <api-base-url> --output json | jq -r '.data.form_ref'

Submit a request.

flow catalog request <catalog-item-id> \
  --requester-principal-id <principal-uuid> \
  --requested-for-principal-id <principal-uuid> \
  --justification "CLI smoke test for employee onboarding" \
  --ticket-title "CLI smoke test for employee onboarding" \
  --form-ref <form-ref> \
  --api-base-url <api-base-url>

Command groups

Search and knowledge

Command	Description
`flow search <query>`	Search tickets, knowledge, and other families
`flow knowledge query`	Query team knowledge retrieval

Catalog and access

Command	Description
`flow catalog list`	List requestable catalog items
`flow catalog get <id>`	Fetch one catalog item
`flow catalog schema <id>`	Show request form schema
`flow catalog request <id>`	Submit an automation request
`flow access-request list` / `get`	Read access requests
`flow access-grant list` / `get` / `revoke` / `replace`	Manage grants
`flow access-review campaign-create` / `decide`	Access review campaigns
`flow approval-request get` / `decide`	Act on approval requests

Automations and runs

Command	Description
`flow workflow publish`	Publish a workflow revision
`flow workflow unpublish`	Unpublish a workflow
`flow workflow rollback`	Roll back to a prior published revision
`flow workflow-run start`	Start a run
`flow workflow-run get`	Inspect a run

Flow assistant

Command	Description
`flow helper turn`	Run a read-only Flow turn from the terminal

Webhooks and audit

Command	Description
`flow webhook endpoint list` / `create` / `test` / `rotate-secret`	Manage outbound webhook endpoints
`flow webhook endpoint metrics <id>`	View delivery metrics for an endpoint
`flow webhook delivery list` / `attempts` / `replay`	Inspect deliveries
`flow webhook event-list`	List webhook events
`flow audit list`	Read audit evidence

API keys and setup

Command	Description
`flow api-key list` / `create`	Manage local scoped API keys
`flow api-key revoke` / `rotate`	Revoke or rotate an API key
`flow setup status`	Inspect admin activation setup posture
`flow elevation start` / `list`	Local elevation sessions for privileged commands
`flow elevation end` / `revoke`	End or revoke an elevation session

Choosing between text and JSON output

Use --output text for interactive terminal use (default).
Use --output json in scripts. Pipe to jq for field extraction.

Errors print a title, detail, and optional problem code. With --verbose, request and correlation IDs help your administrator trace failures.

Get started

Work setup

Requests

Product areas

Channels

Access management

Administration

Troubleshooting

Security

Developers

First catalog request from the CLI

Command groups

Search and knowledge

Catalog and access

Automations and runs

Flow assistant

Webhooks and audit

API keys and setup

Choosing between text and JSON output

Get started

Work setup

Requests

Product areas

Channels

Access management

Administration

Troubleshooting

Security

Developers

​First catalog request from the CLI

​Command groups

​Search and knowledge

​Catalog and access

​Automations and runs

​Flow assistant

​Webhooks and audit

​API keys and setup

​Choosing between text and JSON output

​Related topics

First catalog request from the CLI

Command groups

Search and knowledge

Catalog and access

Automations and runs

Flow assistant

Webhooks and audit

API keys and setup

Choosing between text and JSON output

Related topics