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

# CLI

> Create, manage, and trigger workflows from the command line

The Kestrel CLI lets you manage workflows from your terminal. Use it for scripting, CI/CD integration, and day-to-day workflow management.

## Installation

### Homebrew (macOS / Linux)

```bash theme={null}
brew install KestrelAI/tap/kestrel
```

### Binary Download

Download the latest release from [GitHub Releases](https://github.com/KestrelAI/kestrel-cli/releases):

```bash theme={null}
# macOS (Apple Silicon)
curl -L https://github.com/KestrelAI/kestrel-cli/releases/latest/download/kestrel_darwin_arm64.tar.gz | tar xz
sudo mv kestrel /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/KestrelAI/kestrel-cli/releases/latest/download/kestrel_darwin_amd64.tar.gz | tar xz
sudo mv kestrel /usr/local/bin/

# Linux (x64)
curl -L https://github.com/KestrelAI/kestrel-cli/releases/latest/download/kestrel_linux_amd64.tar.gz | tar xz
sudo mv kestrel /usr/local/bin/
```

## Authentication

### Create an Account

New to Kestrel? You can sign up directly from the terminal:

```bash theme={null}
kestrel register
```

You'll be prompted for a work email and password (8–30 characters, hidden input). If email verification is enabled on the server, a 6-character code is sent to your inbox — enter it at the prompt and you're logged in automatically. You can also verify later:

```bash theme={null}
kestrel verify-email <code>
```

Non-interactive usage (e.g. from a coding agent or script):

```bash theme={null}
kestrel register --email you@company.com --password '...' --server https://platform.usekestrel.ai
kestrel verify-email ABC123
```

After verification the CLI saves your session to `~/.kestrel/config.json` and prints suggested next steps (`kestrel integrations connect ...`).

### API Key (recommended)

Create an API key in the Kestrel platform under **Workflows > API Keys**, then:

```bash theme={null}
kestrel auth kestrel_sk_...
```

### Email / Password

```bash theme={null}
kestrel login
```

You'll be prompted for your server URL, email, and password. Credentials are stored locally at `~/.kestrel/config.json`.

```bash theme={null}
kestrel login --server https://platform.usekestrel.ai --email you@company.com
```

### Check Status

```bash theme={null}
kestrel status
```

### Log Out

```bash theme={null}
kestrel logout
```

## Workflow Commands

### List workflows

```bash theme={null}
kestrel workflows list
kestrel workflows list --status active
```

Aliases: `kestrel wf list`

### Get workflow details

Shows the workflow definition, trigger config, and an ASCII diagram of the workflow DAG:

```bash theme={null}
kestrel workflows get <workflow-id>
```

### Create a workflow from file

```bash theme={null}
kestrel workflows create --file workflow.json
```

### Generate from natural language

Use the AI agent to generate a workflow from a description:

```bash theme={null}
kestrel workflows generate "When a pod crashloops, run RCA, create a Jira ticket, and notify #incidents on Slack"
```

Add `--save` to immediately save as a draft:

```bash theme={null}
kestrel workflows generate --save "When a PagerDuty alert fires, investigate the cluster and post findings to Slack"
```

### Edit a workflow

```bash theme={null}
kestrel workflows edit <workflow-id> --name "New Name"
kestrel workflows edit <workflow-id> --description "Updated description"
```

### Delete a workflow

```bash theme={null}
kestrel workflows delete <workflow-id>
```

### Activate / Pause

```bash theme={null}
kestrel workflows activate <workflow-id>
kestrel workflows pause <workflow-id>
```

### Duplicate

```bash theme={null}
kestrel workflows duplicate <workflow-id>
kestrel workflows duplicate <workflow-id> --name "Copy of my workflow"
```

### Test a workflow

Run a dry-run execution:

```bash theme={null}
kestrel workflows test <workflow-id>
```

### Request a workflow

Submit a natural language request to trigger a matching workflow. This is the CLI equivalent of `/kestrel-workflow` in Slack or the "Make a Request" page in the Kestrel Platform UI:

```bash theme={null}
kestrel workflows request "provision an MSK cluster with 3 brokers in us-east-1"
kestrel workflows request "scale the payments deployment to 5 replicas"
kestrel workflows request "create a DNS record for api.example.com in Cloudflare"
kestrel workflows request "add a new PagerDuty escalation policy for the payments team"
```

If the matched workflow requires additional parameters, you'll be prompted interactively:

```
$ kestrel workflows request "create a configmap"
  Routing request: create a configmap

  ! Matched workflow: On-Demand K8s Resource Provision
  Extracted: resource_type=ConfigMap

  Please provide the following details:

  cluster: prod-cluster
  namespace: payments
  name: app-config

  Submitting with parameters...

  ✓ Matched workflow: On-Demand K8s Resource Provision
  ✓ Workflow is now executing.
```

If no workflow matches your request, the CLI asks whether you want to send it to your platform team as a workflow request (instead of filing one automatically):

```
$ kestrel workflows request "set up a Redis cluster for the cache layer"
  Routing request: set up a Redis cluster for the cache layer

  ✗ No matching workflow found
  Category: general

  Send this to your platform team as a workflow request? They can
  create a workflow to handle this type of request. [y/N]: y

  ✓ Request sent to your platform team.
  Request ID: 4f8a...
```

Answering `n` (or pressing Enter) dismisses the request — it won't appear in the platform's Workflow Requests page.

## Execution Commands

```bash theme={null}
kestrel workflows executions <workflow-id>
kestrel workflows executions <workflow-id> --page 2 --page-size 10
```

### Statistics

```bash theme={null}
kestrel workflows stats
```

## Approval Commands

```bash theme={null}
kestrel approvals list
kestrel approvals approve <approval-id>
kestrel approvals approve <approval-id> --justification "Emergency fix"
kestrel approvals reject <approval-id>
```

## Version History & Rollback

```bash theme={null}
kestrel workflows versions <workflow-id>              # List version history
kestrel workflows rollback <workflow-id> --version 3  # Roll back to version 3
```

## Execution Replay

Replay failed executions from the beginning or from the failed step:

```bash theme={null}
kestrel workflows replay <execution-id>                   # Replay from beginning
kestrel workflows replay <execution-id> --from-failed     # Replay from failed step
```

## Request Commands

```bash theme={null}
kestrel requests list
kestrel requests approve <request-id>
kestrel requests reject <request-id>
```

## API Key Commands

```bash theme={null}
kestrel apikeys list
kestrel apikeys create <name>
kestrel apikeys create <name> --scopes "workflows:read,catalog:read" --expires-in 90d
kestrel apikeys revoke <key-id>
kestrel apikeys delete <key-id>
```

## Catalog and Integrations

```bash theme={null}
kestrel workflows catalog          # Available triggers and actions
kestrel workflows integrations     # Integration connection status
kestrel workflows suggestions      # AI-suggested workflows
```

## Integration Commands

Connect, test, and disconnect integrations (cloud providers, CI/CD, databases, alerting, knowledge sources, and more) directly from the terminal. Aliases: `kestrel integration`, `kestrel int`.

<Note>
  Your API key needs the `integrations:read` and `integrations:manage` scopes to manage integrations. The key created during onboarding includes them by default.
</Note>

### List integrations

Shows every integration with its type and current connection status:

```bash theme={null}
kestrel integrations list
```

### Connect an integration

Each integration has its own `connect` subcommand:

```bash theme={null}
kestrel integrations connect <name>
```

You can pass credentials as flags, but you don't have to — running the bare command walks you through setup interactively:

* The CLI prints setup instructions for the integration (where to create the API token, which permissions to grant, etc.), mirroring the platform UI.
* It prompts for each required value. **Secrets are read with hidden input** — they never appear on the command line or in your shell history.

```bash theme={null}
$ kestrel integrations connect cloudflare
Connecting Cloudflare

  API token: Cloudflare dashboard -> My Profile -> API Tokens -> Create Token -> ...
  Account ID: in the dashboard URL — dash.cloudflare.com/<account-id>/home.

API token (hidden):
Cloudflare account ID: 023e105f4ecef8ad9ca31a8372d0c353
✓ Cloudflare connected
```

To see the flags and setup instructions for any integration:

```bash theme={null}
kestrel integrations connect <name> --help
```

Non-secret values can be passed as flags; file-based credentials support a `--<flag>-file` variant:

```bash theme={null}
kestrel integrations connect terraform --organization my-org
kestrel integrations connect nebius --credentials-file authorized-key.json
kestrel integrations connect confluence --base-url https://acme.atlassian.net --email me@acme.com
```

### Connection types

| Type      | Integrations                                                                                                                                                                                         | How it works                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Token     | Cloudflare, PagerDuty, Datadog, ArgoCD, Jenkins, CircleCI, Terraform Cloud, Pulumi Cloud, Vercel, Railway, Fly.io, Nebius, Beam, Daytona, Supabase, PlanetScale, Neon, ClickHouse, PostHog, and more | Prompts for API tokens/credentials (hidden input) and connects immediately                                  |
| OAuth     | GitHub, GitLab, Slack                                                                                                                                                                                | Prints an authorization/install URL to open in your browser                                                 |
| Knowledge | Jira, Linear, Confluence, Notion, Glean                                                                                                                                                              | Connects and immediately runs a connection test                                                             |
| Cluster   | Kubernetes                                                                                                                                                                                           | Mints an operator token, writes a Helm values file, and prints the `helm install` command                   |
| Cloud     | AWS, OCI                                                                                                                                                                                             | AWS is a two-step IAM role flow (bootstrap, then verify with `--role-arn`); OCI prompts for API key details |

### Test a connection

```bash theme={null}
kestrel integrations test <name>
```

Supported for token integrations and knowledge sources.

### Disconnect an integration

```bash theme={null}
kestrel integrations disconnect <name>
```

OAuth, cluster, and cloud integrations must be disconnected in the Kestrel UI.