CLI reference

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 the flags on a specific command.

Common tasks

You want to…	Command
See or switch your account	`adk profiles list` · `adk profiles set <name>`
Use a different account once	`adk <command> --profile <name>`
Link to a production bot	`adk link`
Develop against your dev bot	`adk dev`
Chat with your agent	`adk chat`
Ship to production	`adk deploy`
Add an integration	`adk integrations add <name>`
Configure it	`adk integrations configure <alias> --set key=value`
Promote dev to prod	`adk integrations copy --from dev --to prod`
Open the Dev Console	`adk dashboard` (or bare `adk`)
Share or move a project	`adk export` then `adk import`
Upgrade a 1.x project	`adk project upgrade`

Global flags

These 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 (or --format text) for machine-readable output. A few interactive commands don’t: dev, login, profiles, self-upgrade, telemetry, theme, run, and assets pull.

Project

Command	Description
`adk init [name]`	Scaffold a new project
`adk dev`	Start development mode with hot reloading
`adk build`	Build the agent for production
`adk check`	Validate project structure, config, and primitives
`adk status`	Show project status, integrations, and server state
`adk link`	Link the project to a workspace and bot
`adk deploy`	Deploy the agent to production
`adk project upgrade`	Apply ADK compatibility updates to a 1.x project

`adk init`

adk init my-agent

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

`adk dev`

Runs your agent locally against your development bot and starts the Dev Console.

adk dev

Flag	Description
`-p, --port <port>`	Development server port (default: `3000`)
`--port-console <port>`	Dev Console port (default: `3001`)
`--otlp`	Export traces to an OTLP collector (default port `4318`)
`--port-otlp <port>`	OTLP collector port (Jaeger, otel-tui, etc.)
`--no-watch`	Disable file watching and hot reload
`--non-interactive`	Emit structured NDJSON events instead of the status panel
`-v, --verbose`	Show additional details

`adk deploy`

Ships code and config to your production bot.

adk deploy

Flag	Description
`-e, --env <environment>`	Deployment environment (default: `production`)
`-y, --yes`	Auto-approve preflight changes without prompting
`--dry-run`	Compute the deploy plan without applying changes
`--confirm-storage-changes`	Confirm destructive storage changes (table/KB/asset deletions)
`--allow-unconfigured`	Deploy even if enabled dependencies are unconfigured (ships them inert)

`adk link`

Points the project at a production bot and writes agent.json. See Project setup.

adk link --workspace <id> --bot <id>

Flag	Description
`--workspace <id>`	Workspace ID
`--bot <id>`	Production bot ID
`--dev <devBotId>`	Also record a development bot ID
`--api-url <url>`	Botpress API URL
`--local`	Write the whole link to `agent.local.json` instead
`-f, --force`	Overwrite an existing `agent.json`

Dependencies

Integrations, plugins, and interfaces are Cloud-first: these commands read and write your bot’s Cloud state. They default to your development bot; pass --target prod to act on production. See Managing dependencies.

`adk integrations`

Command	Description
`adk integrations add <name>`	Add an integration (e.g. `slack` or `slack@1.4.2`)
`adk integrations remove <alias>`	Remove an integration
`adk integrations upgrade <alias>`	Upgrade an integration (`--to <version>`)
`adk integrations enable <alias>`	Enable an integration
`adk integrations disable <alias>`	Disable an integration
`adk integrations configure <alias>`	Set config values (`--set k=v`, `--unset k`)
`adk integrations list`	List installed integrations (`--verbose` for config)
`adk integrations status`	Show each integration’s capability state + remediation
`adk integrations info <name>`	Show registry details for an integration
`adk integrations search [query]`	Search the registry (`--interface <name>` to filter)
`adk integrations copy`	Copy state between envs (`--from`, `--to`)
`adk integrations diff`	Show dependency state differences

Common flags: --target dev|prod, --alias <alias>, and --config key=value (repeatable) on add.

adk integrations add stripe@1.4.2
adk integrations configure stripe --set apiKey=sk-...
adk integrations copy --from dev --to prod --dry-run

`adk plugins`

adk plugins mirrors the full integration verb set (add, remove, upgrade, enable, disable, configure, list, status, info, search, copy, diff) and adds interface wiring:

Flag	Description
`--dep iface=alias`	On `add`: wire an interface dependency to an integration alias (repeatable)
`--map iface=alias`	On `configure`: rewire an interface dependency

adk plugins add hitl --dep hitl=hitl
adk plugins configure hitl --map hitl=zendesk

`adk interfaces`

Interfaces are read-only, so you can only inspect them:

Command	Description
`adk interfaces list`	List built-in interfaces
`adk interfaces info <name>`	Show details for an interface (e.g. `llm`)

`adk dependencies`

Portable dependency snapshots, separate from the generated .adk/dependencies/ cache:

Command	Description
`adk dependencies export [output]`	Export integration and plugin state to a JSON file (`--no-config`)
`adk dependencies import <file>`	Import a snapshot into an environment (`--dry-run`, `--yes`)

Project portability

Command	Description
`adk export [output]`	Bundle the project into a portable `.adk` archive (`--no-config`)
`adk import <archive> [directory]`	Restore an archive into a new directory and link or create bots

Dev processes

Command	Description
`adk dashboard`	Open the Dev Console, or print its address (`--no-browser`, `--format json`)
`adk ps`	List running ADK dev processes (`--wide`, `--watch [seconds]`, `--cloud`)
`adk kill [targets...]`	Stop running dev agents (`--all`, `--current`, `--dry-run`)
`adk home`	Open the Dev Console landing screen (also runs when you call bare `adk` outside a project)

Configuration and secrets

All of these accept --prod to target production instead of dev. See Configuration.

Command	Description
`adk config`	Validate and fill missing config values
`adk config:get <key>`	Read a config value
`adk config:set <key> <value>`	Set a config 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 models for the current bot

Chat and testing

Command	Description
`adk chat`	Chat with your agent in development mode
`adk evals [name]`	Run eval suites
`adk evals runs`	List or show eval run history

`adk chat`

Flag	Description
`--single <message>`	Send one message, print the response, and exit
`--conversation-id <id>`	Continue a conversation
`--timeout <duration>`	Max wait duration (default: `60s`)

`adk evals`

adk evals --tag smoke

Flag	Description
`--tag <tag>`	Run only evals with this tag
`--type <type>`	Run only `capability` or `regression` evals
`--judge-model <model>`	Model for `llm_judge` assertions
`--prod`	Run against the production bot
`-v, --verbose`	Show full details, not just failures
`--server <url>`	Dev server URL (auto-starts if not running)

adk evals runs [runId] lists past runs; add --latest for the most recent, or --limit <n> (default 10).

Logs, traces, and conversations

Command	Description
`adk logs [tokens...]`	Query dev server logs from `.adk/logs/`
`adk traces [tokens...]`	Query trace data from the local store
`adk conversations list`	List recent conversations
`adk conversations show <id>`	Show a conversation timeline (`--include-llm`)
`adk run <script> [args...]`	Run a TypeScript script with the full ADK runtime

`adk logs`

Positional tokens filter the output: a level (error, warning, info), since=<duration>, and limit=<n>.

adk logs error since=1h
adk logs --follow

`adk traces`

Tokens: error, workflow=<name>, action=<name>, trace=<id>, since=<duration>, limit=<n>. Add --include-llm to include LLM instructions, code, and tools.

`adk run`

Runs a script from scripts/ against your dev bot. Pass --prod to use the production bot, and -f, --force to regenerate the bot project first.

Workflows

Command	Description
`adk workflows`	List discovered workflows
`adk workflows inspect <name>`	Inspect a workflow’s schema and metadata
`adk workflows run <name> [payload]`	Run a workflow (`--wait`, `--timeout`)
`adk workflows runs [id]`	List workflow runs, or show one by ID

Knowledge and assets

Command	Description
`adk kb sync`	Sync knowledge bases (requires `--dev` or `--prod`)
`adk assets sync`	Sync assets with remote storage
`adk assets list`	List asset files (`--local`, `--remote`)
`adk assets status`	Show asset sync status
`adk assets pull`	Download remote assets to the local directory

adk kb sync also accepts --dry-run, -y/--yes, --confirm-storage-changes, and --force.

AI assistants

Command	Description
`adk agent0 upgrade`	Create or update the project’s Agent(0) capability bundle
`adk ai-upgrade`	Update ADK skills and slash commands for external coding agents

Account

Command	Description
`adk login`	Authenticate with your Botpress account
`adk logout`	Remove credentials for the current or named profile
`adk profiles list`	List configured profiles
`adk profiles set [profile]`	Switch to a different profile
`adk self-upgrade [version]`	Upgrade the ADK CLI (alias: `self-update`)
`adk telemetry`	Manage telemetry (`--status`, `--enable`, `--disable`)
`adk theme`	Set the CLI theme (`--set dark\|light\|system`)

`adk login`

adk login                       # interactive
adk login --profile work        # save under a named profile
adk login --token <token>       # non-interactive (also reads $BOTPRESS_TOKEN)

Delete a profile with adk logout --profile <name>. See Profiles.