> ## Documentation Index
> Fetch the complete documentation index at: https://docs.letsflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Flow CLI command reference for integrators, builders, and operators.

The Flow command-line interface (CLI) (`flow`) is a command-line client for the same REST API documented in [API Reference](/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](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

<Steps>
  <Step title="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.
  </Step>

  <Step title="List catalog items.">
    ```bash theme={null}
    flow catalog list --api-base-url <api-base-url>
    ```
  </Step>

  <Step title="Inspect request schema.">
    ```bash theme={null}
    flow catalog schema <catalog-item-id> --api-base-url <api-base-url>
    ```
  </Step>

  <Step title="Get the form reference.">
    The default text output does not include `form_ref`. Request JSON output and extract it:

    ```bash theme={null}
    flow catalog schema <catalog-item-id> --api-base-url <api-base-url> --output json | jq -r '.data.form_ref'
    ```
  </Step>

  <Step title="Submit a request.">
    ```bash theme={null}
    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>
    ```
  </Step>
</Steps>

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

## Related topics

* [Hosted MCP](/setup/mcp)
* [API Reference](/api-reference)
* [Day 1 setup](/setup/day-1-setup)
* [Automations](/setup/workflows)
* [Monitor automations](/automations/monitor)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.