docs/adk/cli-reference.mdx at 8ae9d91fb85d005a2d1c4f27e776d3058cc8c4f7 · botpress/docs

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:

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

When deploying, adk deploy warns if an integration is on a different version in dev than in prod. The warning shows the version difference per integration and suggests running adk integrations copy --from dev --to prod --dry-run to preview, then adk integrations copy --from dev --to prod --yes to promote. It does not block the deploy.

`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)

`adk login`

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`)

Navigation Menu

Uh oh!

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`

Uh oh!

FilesExpand file tree

cli-reference.mdx

Latest commit

History

cli-reference.mdx

File metadata and controls

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

`adk init`

`adk dev`

`adk deploy`

`adk link`

`adk add`

`adk search`

`adk list`

`adk info`

`adk chat`

`adk evals`

`adk evals runs`

`adk workflows run`

`adk logs`

`adk traces`

`adk run`

`adk kb sync`

`adk assets sync`

`adk assets list`

`adk mcp`

`adk mcp:init`

`adk login`

`adk self-upgrade`

`adk telemetry`

`adk theme`