CLI Commands Reference

Overview

The ADK CLI provides four main commands for managing your AI agent projects. Each command is designed for specific workflows in the development lifecycle.

adk <command> [options]

Global Options

Version

Display the CLI version:

adk --version
adk -v

Help

Display help information:

adk --help
adk <command> --help

adk new

Create a new ADK project from a starter template.

Usage

adk new [project-name] [options]

Arguments

project-name (optional) - Name of the project directory to create. If omitted, you’ll be prompted.

Options

Option	Alias	Description
`--template <name>`	`-t`	Template to use without prompt

Available Templates

simple-agent - Basic agent with chat capabilities
discord-bot - Agent integrated with Discord
telegram-bot - Agent integrated with Telegram
hono-server - Web server with agent endpoints
mcp-starter - Model Context Protocol server
shade-agent - Near Shade Agent starter
next-js-starter - Full-stack agent app with Next.js and Tailwind

Interactive Workflow

When you run adk new without arguments, the CLI guides you through:

Project Name

Enter your project name (validated for spaces and existing directories)

Template Selection

Choose from the available starter templates

Package Manager

Select your preferred package manager (auto-detects available options)

Dependency Installation

Choose whether to install dependencies automatically

MCP Documentation Setup

Optionally configure the ADK docs MCP server for your IDE (Cursor, Claude, Windsurf, or other)

Examples

Interactive mode:

adk new

With project name:

adk new my-discord-bot

With template specified:

adk new my-agent --template simple-agent

Full non-interactive example:

adk new weather-bot -t telegram-bot

Terminal Output

$ adk new my-agent

🧠 Create new ADK-TS project

? What is your project name? my-agent
? Which template would you like to use?
  🤖 Simple Agent - Basic agent with chat capabilities

✔ Template downloaded!
? Which package manager would you like to use?
  ⚡ pnpm
? Install dependencies? Yes
✔ Dependencies installed!
? Set up ADK docs MCP server for your IDE? Yes
? Which IDE or environment are you using?
  Cursor / VS Code (Cursor extension)
✔ MCP docs server configured for Cursor!

🎉 Project created successfully!

Next steps:
  cd my-agent
  npm run dev

Happy coding! 🚀

adk run

Start an interactive chat session with an agent in your project.

Usage

adk run [agent-path] [options]

Arguments

agent-path (optional) - Relative path to a specific agent file

Options

Option	Alias	Description
`--server`	`-s`	Start API server only (no chat interface)
`--host <host>`	`-h`	Host for server or API URL target
`--verbose`		Enable verbose logging
`--hot`		Enable hot reloading of agents
`--watch <paths>`		Comma-separated paths to watch for hot reload

Modes

Interactive Chat (Default)

Starts an interactive terminal chat session with your agent:

adk run

Features:

Auto-discovers agents in your project
Markdown rendering in the terminal
Streaming responses with spinner
Multi-agent selection when multiple agents exist
Exit with Ctrl+C or type exit/quit

Server Only Mode

Start the API server without the interactive chat interface:

adk run --server

Useful for:

Running agents as a background service
Integration with external tools
Development with custom frontends

Hot Reload Mode

Automatically reload agents when files change:

adk run --hot

Watch additional directories:

adk run --hot --watch src/tools,src/models

Examples

Basic interactive chat:

adk run

Chat with specific agent:

adk run agents/weather-agent.ts

Server mode with custom host:

adk run --server --host 0.0.0.0

Development with hot reload:

adk run --hot --verbose

Watch custom paths:

adk run --hot --watch src/utils,src/config

Terminal Output

$ adk run

🤖 ADK Agent Chat

? Choose an agent to chat with:
  Weather Assistant (agents/weather.ts)

💬 Message: What's the weather like today?

🤖 Thinking...

🤖 Weather Assistant:

Based on current conditions, it's sunny with a temperature of 72°F.
Perfect weather for outdoor activities!

💬 Message: _

adk serve

Start an HTTP API server for agent management and interaction.

Usage

adk serve [options]

Options

Option	Alias	Description
`--port <port>`	`-p`	Port for the server (default: 3210)
`--host <host>`	`-h`	Host address (default: localhost)
`--dir <directory>`	`-d`	Directory to scan for agents (default: cwd)
`--quiet`	`-q`	Reduce logging output
`--swagger`		Force enable OpenAPI documentation
`--no-swagger`		Disable OpenAPI documentation

API Endpoints

The server exposes the following REST endpoints:

Health Check

GET /health

Returns server health status.

List Agents

GET /api/agents

Returns all discovered agents. Response:

[
  {
    "relativePath": "agents/weather.ts",
    "name": "Weather Assistant",
    "absolutePath": "/path/to/project/agents/weather.ts"
  }
]

Send Message

POST /api/agents/:agentPath/message

Request Body:

{
  "message": "What's the weather like?"
}

Response:

{
  "response": "The current weather is sunny with 72°F...",
  "agentName": "Weather Assistant"
}

OpenAPI Documentation

When enabled, Swagger UI is available at:

http://localhost:3210/api-docs

Examples

Start with defaults:

adk serve

Custom port and host:

adk serve --port 8080 --host 0.0.0.0

Scan specific directory:

adk serve --dir ./src/agents

Quiet mode for production:

adk serve --quiet --port 3000

Enable Swagger in production:

NODE_ENV=production adk serve --swagger

Terminal Output

$ adk serve

🚀 ADK Server starting on http://localhost:3210
✅ Server ready
Press Ctrl+C to stop the server

adk web

Start a web interface for testing and interacting with agents visually.

Usage

adk web [options]

Options

Option	Alias	Description
`--port <port>`	`-p`	Port for API server (default: 3210)
`--host <host>`	`-h`	Host address (default: localhost)
`--dir <directory>`	`-d`	Directory to scan for agents (default: cwd)
`--web-url <url>`		Use hosted web UI at specified URL

Modes

Bundled Mode (Default)

Serves the web UI from bundled assets on the same port as the API:

adk web

The web interface and API are both available at http://localhost:3210.

Hosted Mode

Use the hosted web interface with a local API server:

adk web --web-url https://adk-web.iqai.com

If bundled assets are not available (e.g., during development), the CLI automatically falls back to hosted mode.

Features

Visual Chat Interface - Rich web-based chat UI
Agent Selection - Dropdown to switch between agents
Markdown Rendering - Full markdown support in responses
Code Highlighting - Syntax highlighting for code blocks
Session Persistence - Maintains conversation history
Responsive Design - Works on desktop and mobile

Examples

Start with defaults:

adk web

Custom port:

adk web --port 8080

Scan specific directory:

adk web --dir ./src/agents

Use hosted web UI:

adk web --web-url https://adk-web.iqai.com

Custom host and port:

adk web --host 0.0.0.0 --port 3000

Terminal Output

Bundled mode:

$ adk web

🌐 Starting ADK Web Interface...
✅ Web UI and API running on the same server
🔗 Open in your browser: http://localhost:3210
Press Ctrl+C to stop the server

Hosted mode:

$ adk web

🌐 Starting ADK Web Interface...
⚠️  Bundled web assets not found. Falling back to hosted version.
   Run 'pnpm build' in the adk-cli package to enable bundled mode.
🔗 Open this URL in your browser: https://adk-web.iqai.com
   API Server: http://localhost:3210
Press Ctrl+C to stop the server

Environment Variables

The CLI respects these environment variables across all commands:

# Enable detailed framework logging
export ADK_DEBUG=true

# Enable verbose output
export ADK_VERBOSE=true

# Set environment mode
export NODE_ENV=production

Tips & Best Practices

Development Workflow

Use adk run --hot during development for instant feedback on agent changes

Testing Agents

Use adk web for visual testing and adk run for quick terminal-based testing

Production Deployment

Use adk serve --quiet --port 3000 for production API servers

Multi-Agent Projects

Organize agents in an agents/ directory for automatic discovery

Getting Started

Core Concepts

Agents

Models & Providers

Tools

Memory & State

Advanced Features

CLI Tool

Examples

​Overview

​Global Options

​Version

​Help

​adk new

​Usage

​Arguments

​Options

​Available Templates

​Interactive Workflow

​Examples

​Terminal Output

​adk run

​Usage

​Arguments

​Options

​Modes

​Interactive Chat (Default)

​Server Only Mode

​Hot Reload Mode

​Examples

​Terminal Output

​adk serve

​Usage

​Options

​API Endpoints

​Health Check

​List Agents

​Send Message

​OpenAPI Documentation

​Examples

​Terminal Output

​adk web

​Usage

​Options

​Modes

​Bundled Mode (Default)

​Hosted Mode

​Features

​Examples

​Terminal Output

​Environment Variables

​Tips & Best Practices

Development Workflow

Testing Agents

Production Deployment

Multi-Agent Projects

Build docs developers (and LLMs) love

Overview

Global Options

Version

Help

adk new

Usage

Arguments

Options

Available Templates

Interactive Workflow

Examples

Terminal Output

adk run

Usage

Arguments

Options

Modes

Interactive Chat (Default)

Server Only Mode

Hot Reload Mode

Examples

Terminal Output

adk serve

Usage

Options

API Endpoints

Health Check

List Agents

Send Message

OpenAPI Documentation

Examples

Terminal Output

adk web

Usage

Options

Modes

Bundled Mode (Default)

Hosted Mode

Features

Examples

Terminal Output

Environment Variables

Tips & Best Practices