CLI reference - Botpress

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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)

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

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:

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:

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:

adk theme --set dark
adk theme --set light

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

​Global flags

​Project

​adk init

​adk dev

​adk deploy

​adk link

​Integrations

​adk add

​adk search

​adk list

​adk info

​Configuration and secrets

​Chat and testing

​adk chat

​adk evals

​adk evals runs

​Workflows

​adk workflows run

​Debugging

​adk logs

​adk traces

​adk run

​Knowledge bases

​adk kb sync

​Assets

​adk assets sync

​adk assets list

​AI assistants

​adk mcp

​adk mcp:init

​Account

​adk login

​adk self-upgrade

​adk telemetry

​adk theme