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

# Command Line Interface (CLI)

> Manage Kadoa workflows from the terminal

The Kadoa CLI offers similar features to the [MCP Server](/docs/sdk/mcp) — workflow, monitor, notification, variable, template, and change operations available from your terminal, scripts, and CI/CD pipelines. It wraps the [Node SDK](/docs/sdk/introduction) and runs on Node 18+.

## Prerequisites

* A [Kadoa account](https://kadoa.com/signup)
* The Kadoa CLI installed (see [Installation](/docs/sdk/introduction#cli))

## Authentication

The CLI authenticates with OAuth — there is no API key. `kadoa login` opens your browser, signs you in via Kadoa SSO, and stores the access + refresh tokens in `~/.kadoa/config.json` (mode `0600`). Tokens refresh automatically; you stay logged in until you `kadoa logout`.

```bash theme={null}
# Interactive OAuth login
kadoa login

# Sign out (removes ~/.kadoa/config.json)
kadoa logout
```

Check your current auth status, active team, and role:

```bash theme={null}
kadoa whoami
#   Email: john@acme.com
#   Name:  John Doe
#   Auth:  OAuth (config)
#   Token: valid
#   Active team: Acme Corp [ADMIN]
```

## Quick Start

<Steps>
  <Step title="Log in">
    Authenticate via your browser — no API key required.

    ```bash theme={null}
    kadoa login
    ```
  </Step>

  <Step title="Create a workflow">
    Describe what to extract in natural language and point it at a URL.

    ```bash theme={null}
    kadoa create "Extract product names and prices" --url https://sandbox.kadoa.com/ecommerce
    ```
  </Step>

  <Step title="Run it and fetch results">
    Trigger a run, then read the extracted data.

    ```bash theme={null}
    kadoa run <workflowId>
    kadoa data <workflowId>
    ```
  </Step>

  <Step title="Export the dataset">
    Stream the full dataset to a file.

    ```bash theme={null}
    kadoa export <workflowId> --format csv --out products.csv
    ```
  </Step>
</Steps>

## Commands

### Global Options

| Option          | Description       |
| --------------- | ----------------- |
| `--json`        | Force JSON output |
| `-V, --version` | Show version      |
| `-h, --help`    | Show help         |

### Auth & Team

| Command                    | Description                                               |
| -------------------------- | --------------------------------------------------------- |
| `kadoa login`              | OAuth login (saves credentials to `~/.kadoa/config.json`) |
| `kadoa logout`             | Remove stored credentials                                 |
| `kadoa whoami`             | Show current user, team, and role                         |
| `kadoa team list`          | List your teams and see which is active                   |
| `kadoa team switch [team]` | Switch active team by name or ID                          |

### Workflows

| Command                             | Description                                                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `kadoa create <prompt> --url <url>` | Create a prompt-driven workflow. Repeat `--url` for multi-URL workflows on the same domain.                                  |
| `kadoa list`                        | List workflows. Flags: `--state <ACTIVE\|FAILED\|PAUSED\|PREVIEW\|VALIDATING>`, `--limit <n>`, `--format <table\|json\|csv>` |
| `kadoa get <id>`                    | Get workflow details                                                                                                         |
| `kadoa run <id>`                    | Run a workflow. `--limit <n>` caps records.                                                                                  |
| `kadoa pause <id>`                  | Pause an ACTIVE workflow so it stops running on its schedule                                                                 |
| `kadoa approve <id>`                | Approve and activate a workflow (also resumes a paused one)                                                                  |
| `kadoa update <id>`                 | Update workflow config. Flags: `--name`, `--url`, `--prompt`, `--schedule`, `--limit`                                        |
| `kadoa delete <id>`                 | Delete a workflow. Use `--force` to skip the confirmation.                                                                   |

`kadoa create` accepts the full flag set: `--name`, `--entity`, `--description`, `--tag`, `--limit`, `--schedule`, `--cron`, plus `--notify-email/--notify-webhook/--notify-slack-channel/--notify-websocket` to wire notifications at creation time.

The `list` and `get` `status` field shows the computed [workflow state](/docs/workflows/states) (Complete, Running, Failed, Paused, Scheduled, etc.) — the same display the dashboard uses.

### Data

| Command             | Description                                                                                                                                                            |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kadoa data <id>`   | Paginated read. Flags: `--limit <n>`, `--page <n>`, `--format <table\|json\|csv>`                                                                                      |
| `kadoa export <id>` | Export the full dataset via signed URL. Flags: `--format <csv\|json>`, `--out <path>`, `--run-id <id>`, `--filters <json>`, `--sort-by <field>`, `--order <asc\|desc>` |

`export` is the right choice for large workflows — it streams the full dataset rather than paginating.

### Real-time Monitors

Real-time monitors watch a page and alert on changes. Each detected change is captured in the `changes` log.

| Command                                     | Description                                                                                                                          |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `kadoa monitor create [prompt] --url <url>` | Create a real-time monitor. At least one `--notify-*` channel is required.                                                           |
| `kadoa changes`                             | List detected changes. Flags: `--workflow <id>`, `--start-date <date>`, `--end-date <date>`, `--skip <n>`, `--limit <n>`, `--format` |
| `kadoa change <changeId>`                   | Show full snapshot and diff for a single detected change                                                                             |

### Notifications

Notifications are split into **channels** (where alerts are delivered: email, webhook, Slack, WebSocket) and **settings** (which events route to which channels).

| Command                                                                         | Description                                                                 |
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `kadoa notifications channels list`                                             | List channels. `--workflow <id>` filters to a workflow.                     |
| `kadoa notifications channels get <id>`                                         | Show details for a single channel                                           |
| `kadoa notifications channels create --type <EMAIL\|WEBHOOK\|SLACK\|WEBSOCKET>` | Create a channel (see flags below)                                          |
| `kadoa notifications channels delete <id>`                                      | Delete a channel. `--force` skips the prompt.                               |
| `kadoa notifications settings list`                                             | List event-to-channel mappings. `--workflow <id>`, `--event <type>` filter. |
| `kadoa notifications settings delete <id>`                                      | Delete a setting (channels are kept)                                        |
| `kadoa notifications configure --event <type>`                                  | One-step setup: create/reuse a channel and wire it to an event              |

`notifications` is aliased as `notify`. `channels create` flags depend on `--type`:

* `EMAIL` → `--recipient <addr>` (repeatable; omit for account default), `--name <name>`
* `WEBHOOK` → `--url <url>`, `--method <method>`, `--auth-bearer <token>` or `--auth-basic <user:pass>`
* `SLACK` → `--slack-channel-id <id>` or `--slack-channel-name <name>` (OAuth) or `--slack-webhook <url>` (legacy)
* `WEBSOCKET` → no extra flags

`configure` mirrors the [MCP `configure_notifications` tool](/docs/sdk/mcp#notifications) — accepts `--workflow`, repeatable `--event` (or `--event all`), and the same `--notify-*` flags as `kadoa create`.

### Variables

Variables are key/value pairs you reference in workflow prompts as `@key`.

| Command                                   | Description                                                 |
| ----------------------------------------- | ----------------------------------------------------------- |
| `kadoa vars list`                         | List variables in the active team                           |
| `kadoa vars get <id>`                     | Show a single variable                                      |
| `kadoa vars create --key <k> --value <v>` | Create a variable. `--type <STRING\|SECRET\|OBJECT\|ARRAY>` |
| `kadoa vars update <id>`                  | Update key, value, or type                                  |
| `kadoa vars delete <id>`                  | Delete a variable. `--force` skips the prompt.              |

`vars` is aliased as `variables`.

### Templates

Templates are reusable, versioned workflow configurations (prompt + schema + notifications).

| Command                                | Description                                                                                                            |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `kadoa templates list`                 | List templates in the active team                                                                                      |
| `kadoa templates get <id>`             | Show a template with all published versions                                                                            |
| `kadoa templates create --name <name>` | Create an empty template. `--description <text>`                                                                       |
| `kadoa templates update <id>`          | Update name or description                                                                                             |
| `kadoa templates delete <id>`          | Archive a template (existing workflows are unaffected). `--force` skips the prompt.                                    |
| `kadoa templates version <id>`         | Publish a new version. `--prompt <text>`, `--schema-id <id>` or `--schema-entity <name>`                               |
| `kadoa templates save <workflowId>`    | Save a workflow as a new template (`--name`, `--description`) or as a new version of an existing one (`--template-id`) |
| `kadoa templates schemas <id>`         | List schemas associated with a template                                                                                |

### Shell Completion

Tab-complete subcommands, flags, and workflow IDs:

```bash theme={null}
# Zsh — add to ~/.zshrc
eval "$(kadoa completion zsh)"

# Bash — add to ~/.bashrc
eval "$(kadoa completion bash)"
```

Zsh shows workflow names inline: `kadoa get <TAB>` displays `abc123 -- My Workflow`.

## Output Formatting

The CLI auto-detects the right format: tables in interactive terminals, JSON when piping or redirecting. Override with `--json` or `--format`.

```bash theme={null}
kadoa list --json                        # Force JSON
kadoa data <id> --format csv             # CSV output
kadoa list --json | jq '.[].id'          # Pipe to jq
kadoa data <id> --format csv > data.csv  # Save to file
```

## CI/CD

Supply OAuth tokens via environment variables and the CLI runs non-interactively:

```yaml theme={null}
# GitHub Actions
env:
  KADOA_ACCESS_TOKEN: ${{ secrets.KADOA_ACCESS_TOKEN }}
  KADOA_REFRESH_TOKEN: ${{ secrets.KADOA_REFRESH_TOKEN }}
steps:
  - run: |
      kadoa run $WORKFLOW_ID --json
      kadoa export $WORKFLOW_ID --format csv --out output.csv
```

## Permissions

The commands you can run depend on your team role. Viewers and Compliance Officers have read-only access — write operations return a 403 with a hint to contact your team admin. The permission matrix matches the [MCP Server tool permissions](/docs/sdk/mcp#permissions).

<Tip>
  Each command also accepts `--help` for the full flag list, e.g. `kadoa create --help`.
</Tip>