> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-pb-update-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> All commands and flags available with the ADK CLI.

The `adk` CLI is how you scaffold, run, deploy, and debug ADK agents. Run `adk --help` for the top-level command list, or `adk <command> --help` for flags on a specific command.

## Global flags

These flags work with every command:

| Flag                  | Description                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------- |
| `--help`, `-h`        | Show help information                                                                                 |
| `--version`, `-V`     | Show version number                                                                                   |
| `--no-cache`          | Disable caching for integration lookups                                                               |
| `--profile <profile>` | Credentials profile to use (overrides the `ADK_PROFILE` environment variable and the current profile) |

Most commands also accept `--format json` for machine-readable output. The following commands don't: `dev`, `login`, `profiles list`, `profiles set`, `upgrade`, `remove`, `self-upgrade`, `telemetry`, `theme`, `mcp`, `mcp:init`, `run`, `assets pull`.

## Project

These commands manage an agent project from scaffold to deploy:

| Command           | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `adk init [name]` | Initialize a new project                                  |
| `adk dev`         | Start development mode with hot reloading                 |
| `adk build`       | Build the agent for production                            |
| `adk deploy`      | Deploy the agent to Botpress Cloud                        |
| `adk check`       | Validate project structure and config (no login required) |
| `adk status`      | Show project status, integrations, and server state       |
| `adk link`        | Link local agent to a workspace and bot                   |

### `adk init`

Scaffold a new agent project. Pass a name, or omit it to be prompted:

```bash theme={null}
adk init my-agent
adk init my-agent --template hello-world
adk init --list-templates
```

| Flag                        | Description                        |
| --------------------------- | ---------------------------------- |
| `-t, --template <template>` | Template to use (default: `blank`) |
| `-y, --yes`, `--defaults`   | Skip prompts, use defaults         |
| `--skip-link`               | Skip the linking step              |
| `--list-templates`          | List available templates and exit  |

### `adk dev`

Start the dev server with hot reload:

```bash theme={null}
adk dev
adk dev --port 3000 --port-console 3001
```

| Flag                    | Description                                            | Default |
| ----------------------- | ------------------------------------------------------ | ------- |
| `-p, --port <port>`     | Bot server port                                        | `3000`  |
| `--port-console <port>` | Dev console port                                       | `3001`  |
| `--otlp`                | Enable OTLP export to external collector (port `4318`) |         |
| `--port-otlp <port>`    | Override the OTLP collector endpoint port              |         |
| `-v, --verbose`         | Show additional details                                |         |
| `--non-interactive`     | Emit structured NDJSON events to stdout                |         |

### `adk deploy`

Deploy the built agent to Botpress Cloud:

```bash theme={null}
adk deploy
adk deploy -y
```

| Flag                      | Description                    | Default      |
| ------------------------- | ------------------------------ | ------------ |
| `-e, --env <environment>` | Deployment environment         | `production` |
| `-y, --yes`               | Auto-approve preflight changes |              |

### `adk link`

Link the local agent to a workspace and bot. Writes to `agent.json`, or to `agent.local.json` with `--local`:

```bash theme={null}
adk link
adk link --workspace wkspace_123 --bot bot_456
```

| Flag               | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `--workspace <id>` | Workspace ID                                                     |
| `--bot <id>`       | Bot ID to link to                                                |
| `--dev <id>`       | Dev bot ID                                                       |
| `--api-url <url>`  | Botpress API URL                                                 |
| `-f, --force`      | Overwrite existing `agent.json`                                  |
| `--local`          | Write to gitignored `agent.local.json` (for multi-dev workflows) |

## Integrations

These commands add, inspect, and manage the integrations your agent depends on:

| Command                     | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `adk add <resource>`        | Add an integration or interface (aliases: `i`, `install`) |
| `adk remove [resource]`     | Remove an integration, interface, or plugin (alias: `rm`) |
| `adk upgrade [integration]` | Upgrade integration(s) to latest version (alias: `up`)    |
| `adk search <query>`        | Search the Botpress Hub                                   |
| `adk list`                  | List installed integrations                               |
| `adk info <name>`           | Show detailed integration info                            |

### `adk add`

Add an integration or interface to your agent. Accepts a name, `workspace/name`, or a specific version:

```bash theme={null}
adk add webchat
adk add slack@latest
adk add slack@0.5.0
adk add my-workspace/custom@1.0.0
adk add interface:translator@1.0.0
adk add webchat --alias custom-webchat
```

| Flag              | Description                   |
| ----------------- | ----------------------------- |
| `--alias <alias>` | Custom alias for the resource |

### `adk search`

Search the Botpress Hub for integrations:

```bash theme={null}
adk search crm
adk search slack --limit 5
```

| Flag               | Description           | Default |
| ------------------ | --------------------- | ------- |
| `--limit <number>` | Max results to return | `20`    |

### `adk list`

List integrations in your project, or all available ones on the Hub:

```bash theme={null}
adk list
adk list --available
```

| Flag          | Description                                          | Default |
| ------------- | ---------------------------------------------------- | ------- |
| `--available` | List all available integrations (not just installed) |         |
| `--limit <n>` | Max results                                          | `50`    |

### `adk info`

Show details for a specific integration. Filter by a single facet or show the full spec:

```bash theme={null}
adk info slack
adk info slack --actions
adk info slack --full
```

| Flag         | Description        |
| ------------ | ------------------ |
| `--actions`  | Show only actions  |
| `--channels` | Show only channels |
| `--events`   | Show only events   |
| `--full`     | Show all details   |

## Configuration and secrets

These commands manage config values and secrets:

| Command                        | Description                                           |
| ------------------------------ | ----------------------------------------------------- |
| `adk config`                   | Validate and fill missing config values interactively |
| `adk config:get <key>`         | Get a configuration value                             |
| `adk config:set <key> <value>` | Set a configuration value                             |
| `adk secret`                   | Show declared secrets and their status                |
| `adk secret:set <key> <value>` | Set a secret value                                    |
| `adk secret:delete <key>`      | Delete a secret                                       |
| `adk models`                   | List available LLM models                             |

All configuration and secret commands accept `--prod` to target the production environment instead of dev.

## Chat and testing

These commands let you send messages to your agent and run eval suites:

| Command                  | Description                      |
| ------------------------ | -------------------------------- |
| `adk chat`               | Interactive chat with your agent |
| `adk evals [name]`       | Run eval suites                  |
| `adk evals runs [runId]` | List or show eval run history    |

### `adk chat`

Open an interactive chat, or send a single message with `--single`. Requires `adk dev` to be running:

```bash theme={null}
adk chat
adk chat --single "What's the status of order 12345?"
adk chat --single "Follow up" --conversation-id <id>
```

| Flag                     | Description               | Default |
| ------------------------ | ------------------------- | ------- |
| `--single <message>`     | Send one message and exit |         |
| `--conversation-id <id>` | Continue a conversation   |         |
| `--timeout <duration>`   | Max wait duration         | `60s`   |

### `adk evals`

Run eval suites. With no arguments, runs all evals; pass a name to run just one:

```bash theme={null}
adk evals
adk evals greeting
adk evals --tag smoke
adk evals --type regression
adk evals -v
```

| Flag                    | Description                                 | Default                 |
| ----------------------- | ------------------------------------------- | ----------------------- |
| `--tag <tag>`           | Run only evals with this tag                |                         |
| `--type <type>`         | Run only `capability` or `regression` evals |                         |
| `--judge-model <model>` | Model for `llm_judge` assertions            |                         |
| `-v, --verbose`         | Show full details for all evals             |                         |
| `--server <url>`        | Dev server URL                              | `http://localhost:3001` |

### `adk evals runs`

List past eval runs, or show the details of a specific one:

```bash theme={null}
adk evals runs
adk evals runs --latest
adk evals runs <run-id> -v
```

| Flag            | Description         | Default |
| --------------- | ------------------- | ------- |
| `--latest`      | Show the latest run |         |
| `--limit <n>`   | Max runs to list    | `10`    |
| `-v, --verbose` | Show full details   |         |

## Workflows

These commands discover and run workflows against the local dev server:

| Command                              | Description                            |
| ------------------------------------ | -------------------------------------- |
| `adk workflows`                      | List all discovered workflows          |
| `adk workflows inspect <name>`       | Inspect a workflow schema and metadata |
| `adk workflows run <name> [payload]` | Run a workflow                         |

### `adk workflows run`

Run a workflow with a JSON payload. Add `--wait` to block until it finishes:

```bash theme={null}
adk workflows run onboarding '{"userId":"123"}'
adk workflows run onboarding '{"userId":"123"}' --wait --timeout 30s
```

| Flag                   | Description                          |
| ---------------------- | ------------------------------------ |
| `--wait`               | Wait for the workflow to finish      |
| `--timeout <duration>` | Max wait duration (implies `--wait`) |

## Debugging

These commands help you inspect what your agent is doing:

| Command                      | Description                                  |
| ---------------------------- | -------------------------------------------- |
| `adk logs [tokens...]`       | Query dev server logs                        |
| `adk traces [tokens...]`     | Query trace data                             |
| `adk run <script> [args...]` | Run a TypeScript script with the ADK runtime |

### `adk logs`

Query logs from `.adk/logs/`. Pass filter tokens as positional arguments, or stream with `--follow`:

```bash theme={null}
adk logs
adk logs error
adk logs warning since=1h
adk logs --follow
adk logs --follow limit=10
```

| Token              | Description                                               |
| ------------------ | --------------------------------------------------------- |
| `error`            | Show errors only                                          |
| `warning`          | Show errors + warnings                                    |
| `info`             | Show errors + warnings + info                             |
| `since=<duration>` | Only entries newer than duration (e.g. `30s`, `5m`, `1h`) |
| `limit=<n>`        | Max entries to show (default: `50`)                       |

| Flag           | Description                                           |
| -------------- | ----------------------------------------------------- |
| `-f, --follow` | Stream logs in real time                              |
| `--summary`    | Emit a single JSON summary (requires `--format json`) |

### `adk traces`

Query trace data from the local store. Filter tokens narrow by workflow, action, trigger, or drill into a specific trace:

```bash theme={null}
adk traces
adk traces error
adk traces since=1h
adk traces workflow=onboarding
adk traces trace=<id>
adk traces trace=<id> --include-llm
adk traces --follow
```

| Token               | Description                        |
| ------------------- | ---------------------------------- |
| `error`             | Show only error traces             |
| `workflow=<name>`   | Filter by workflow name            |
| `action=<name>`     | Filter by action/tool name         |
| `trigger=<name>`    | Filter by trigger name             |
| `conversation=<id>` | Filter by conversation ID          |
| `trace=<id>`        | Drill into a specific trace        |
| `since=<duration>`  | Only traces newer than duration    |
| `until=<duration>`  | Only traces older than duration    |
| `limit=<n>`         | Max traces to show (default: `20`) |

| Flag            | Description                                        |
| --------------- | -------------------------------------------------- |
| `-f, --follow`  | Stream new traces                                  |
| `--include-llm` | Include LLM instructions and code in drill-in mode |

### `adk run`

Run a TypeScript script with the full ADK runtime, so you can import actions, Zai, and tables directly:

```bash theme={null}
adk run scripts/migrate.ts
adk run scripts/seed.ts --prod
adk run scripts/process.ts arg1 arg2
```

| Flag          | Description                           |
| ------------- | ------------------------------------- |
| `-f, --force` | Force regeneration of the bot project |
| `--prod`      | Use production bot (default: dev)     |

## Knowledge bases

Sync local knowledge base content with Botpress:

| Command       | Description                               |
| ------------- | ----------------------------------------- |
| `adk kb sync` | Synchronize knowledge bases with Botpress |

### `adk kb sync`

Push local KB sources to the dev or prod bot. Use `--dry-run` to preview changes first:

```bash theme={null}
adk kb sync --dev
adk kb sync --prod
adk kb sync --prod --force
adk kb sync --dry-run
```

| Flag        | Description                       |
| ----------- | --------------------------------- |
| `--dev`     | Sync with development bot         |
| `--prod`    | Sync with production bot          |
| `--dry-run` | Preview changes without applying  |
| `-y, --yes` | Skip confirmation prompts         |
| `--force`   | Force re-sync all knowledge bases |

## Assets

Manage static files your agent serves or references:

| Command             | Description                               |
| ------------------- | ----------------------------------------- |
| `adk assets sync`   | Synchronize assets with remote storage    |
| `adk assets list`   | List all asset files                      |
| `adk assets status` | Show asset sync status                    |
| `adk assets pull`   | Download remote assets to local directory |

### `adk assets sync`

Upload local assets to remote storage. Use `--dry-run` to see what would change:

```bash theme={null}
adk assets sync
adk assets sync --dry-run
adk assets sync --force -y
```

| Flag                | Description                      |
| ------------------- | -------------------------------- |
| `--dry-run`         | Preview changes without applying |
| `-y, --yes`         | Skip confirmation prompts        |
| `--bail-on-failure` | Stop on first error              |
| `--force`           | Force re-upload all files        |

### `adk assets list`

List asset files. By default shows both local and remote; filter with `--local` or `--remote`:

```bash theme={null}
adk assets list
adk assets list --local
adk assets list --remote
```

| Flag       | Description             |
| ---------- | ----------------------- |
| `--local`  | Show only local assets  |
| `--remote` | Show only remote assets |

## AI assistants

These commands integrate the ADK with AI coding tools:

| Command        | Description                      |
| -------------- | -------------------------------- |
| `adk mcp`      | Start the MCP server             |
| `adk mcp:init` | Generate MCP configuration files |

### `adk mcp`

Start the MCP server so tools like Claude Code, Cursor, or VS Code can talk to your running dev server:

```bash theme={null}
adk mcp
adk mcp --port 3001
```

| Flag            | Description                          | Default |
| --------------- | ------------------------------------ | ------- |
| `--cwd <path>`  | Working directory for MCP operations |         |
| `--port <port>` | UI server port to connect to         | `3001`  |

### `adk mcp:init`

Generate MCP configuration files for supported AI assistants:

```bash theme={null}
adk mcp:init --all
adk mcp:init --tool claude-code
adk mcp:init --tool vscode cursor
```

| Flag                   | Description                                         |
| ---------------------- | --------------------------------------------------- |
| `--tool <tool...>`     | Specific tool(s): `claude-code`, `vscode`, `cursor` |
| `--all`                | Generate for all supported tools                    |
| `--force`              | Overwrite existing config                           |
| `--project-dir <path>` | ADK project subdirectory (for monorepos)            |

## Account

These commands manage your Botpress credentials and the CLI itself:

| Command                      | Description                                                            |
| ---------------------------- | ---------------------------------------------------------------------- |
| `adk login`                  | Authenticate with Botpress                                             |
| `adk profiles list`          | List authentication profiles                                           |
| `adk profiles set [profile]` | Switch to a different profile                                          |
| `adk self-upgrade [tag]`     | Upgrade ADK CLI to latest (or specific) version (alias: `self-update`) |
| `adk telemetry`              | Manage telemetry preferences                                           |
| `adk theme`                  | Manage CLI theme (dark/light)                                          |

### `adk login`

Authenticate with your Botpress account. Pass `--token` to skip the browser flow:

```bash theme={null}
adk login
adk login --token <token>
adk login --profile staging
```

| Flag                  | Description                            | Default                      |
| --------------------- | -------------------------------------- | ---------------------------- |
| `--token <token>`     | Botpress API token                     |                              |
| `--profile <profile>` | Profile name to save credentials under |                              |
| `--api-url <url>`     | Botpress API URL                       | `https://api.botpress.cloud` |

### `adk self-upgrade`

Upgrade the ADK CLI. Pass a tag (`beta`, `next`) or an explicit version:

```bash theme={null}
adk self-upgrade
adk self-upgrade beta
adk self-upgrade 1.18.0
```

### `adk telemetry`

View or change telemetry preferences. With no flags, prints the current status:

```bash theme={null}
adk telemetry
adk telemetry --enable
adk telemetry --disable
```

| Flag        | Description           |
| ----------- | --------------------- |
| `--status`  | Show telemetry status |
| `--enable`  | Enable telemetry      |
| `--disable` | Disable telemetry     |

### `adk theme`

Switch the CLI theme between dark and light:

```bash theme={null}
adk theme --set dark
adk theme --set light
```

| Flag            | Description                   |
| --------------- | ----------------------------- |
| `--set <theme>` | Set theme (`dark` or `light`) |