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

# Cli reference

***

title: CLI reference
description: 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- | |


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