Commands

adk new

Create a new ADK project from professional templates with interactive setup.

adk new
# or with a specific template
adk new my-agent --template simple-agent

Available Templates:

• simple-agent – Basic agent with chat capabilities and examples
• discord-bot – Agent integrated with Discord bot framework
• telegram-bot – Agent integrated with Telegram bot API
• hono-server – Web server with RESTful agent endpoints
• shade-agent – Agent with Near Shade Agents integration
• mcp-starter – Model Context Protocol server integration

Features:

• Interactive project creation with guided setup
• Automatic dependency installation with package manager detection
• Support for npm, pnpm, yarn, and bun
• Template validation and error handling
• Professional project structure with TypeScript support

Package Managers: The CLI automatically detects available package managers and offers a choice:

• 📦 npm
• ⚡ pnpm
• 🧶 yarn
• 🍞 bun

adk run

Run agents with intelligent discovery and interactive chat interface.

adk run
# Run a specific agent file
adk run path/to/agent.ts
# Server-only mode (no chat)
# Default server URL: http://localhost:8042/
adk run --server
# Make API server accessible from other devices/networks
adk run --server --host 0.0.0.0
# Enable hot reload during development
adk run --hot
# Watch additional paths for changes
adk run --watch src,lib,tools
# Enable verbose logging
adk run --verbose

Options:

• --server – Start API server only (no interactive chat)
• --host <host> – Custom host for server mode (default: localhost)
• --hot – Enable hot reload for live code changes
• --watch <paths> – Comma-separated list of additional paths to watch
• --verbose – Enable detailed logging and diagnostics

Features:

• Auto-discovers agents in the current directory with .gitignore awareness
• Interactive selector if multiple agents are found
• Terminal chat with markdown rendering
• Hot reload support for development workflows

adk web

Launch a React-based web interface for visual agent testing and management. Opens the hosted production interface at adk-web.iqai.com.

adk web
# Use a specific API server port
adk web --port 8080
# Make API server accessible from other devices/networks
adk web --host 0.0.0.0
# Scan a custom directory
adk web --dir ./my-agents
# Use custom deployed web application
adk web --web-url https://my-custom-adk-web.com

Options:

• --port <port> – Port for API server (default: 8042)
• --host <host> – Host for API server (default: localhost). Use 0.0.0.0 to make accessible from other devices on your network
• --dir <directory> – Directory to scan for agents (default: current directory)
• --web-url <url> – URL of any web interface (local or remote) that will connect to your API server

Features:

• Visual agent browser and chat interface
• Real-time agent status monitoring
• Session management and message history
• Responsive design for desktop and mobile
• Automatically starts API server and opens the web interface

Web Interface Options:

• Default (Production): Opens the hosted web interface at adk-web.iqai.com which connects to your local API server
• Custom Web Interface (--web-url): Use any web interface (local or remote) by specifying its URL. The web interface will connect to your local API server to display your agents
• Local Development: Use adk serve to start only the API server, then access any web interface manually. The web interface will connect to the default API server address (http://localhost:8042)

Note: All web interfaces connect to your local API server (default: http://localhost:8042) to display and interact with your agents, regardless of where the web interface itself is hosted. When using a non-default --port, the CLI automatically passes the port as a URL query parameter (e.g., ?port=8080) so the web interface can discover and connect to your API server. This is particularly useful when developing custom web interfaces that need to connect to your local agents.

adk serve

Start a standalone API server for agent management (no chat UI).

adk serve
# Default server URL: http://localhost:8042/
# Custom port
adk serve --port 9000
# Custom host (make accessible from other devices/networks)
adk serve --host 0.0.0.0
# Scan a specific directory
adk serve --dir ./production-agents
# Enable OpenAPI docs (enabled by default)
adk serve --swagger
# Disable OpenAPI docs
adk serve --no-swagger
# Quiet mode (minimal logging)
adk serve --quiet

Options:

• --port <port> – Port for the server (default: 8042)
• --host <host> – Host for the server (default: localhost)
• --dir <directory> – Directory to scan for agents (default: current directory)
• --swagger – Force enable OpenAPI docs
• --no-swagger – Disable OpenAPI docs
• --quiet – Reduce logging output

API Endpoints:

• GET /api/agents – List all discovered agents
• POST /api/agents/refresh – Refresh agent discovery scan
• GET /api/agents/{id}/sessions – List sessions for an agent
• POST /api/agents/{id}/sessions – Create a new session
• DELETE /api/agents/{id}/sessions/{sessionId} – Delete a session
• POST /api/agents/{id}/sessions/{sessionId}/switch – Switch active session
• GET /api/agents/{id}/sessions/{sessionId}/events – Get session events
• GET /api/agents/{id}/sessions/{sessionId}/state – Get session state
• PUT /api/agents/{id}/sessions/{sessionId}/state – Update session state
• GET /api/agents/{id}/messages – Get message history for the active session
• POST /api/agents/{id}/message – Send message to the agent's active session
• GET /health – Health check
• GET /reload/stream – Hot reload event stream
• GET /docs – OpenAPI documentation (when enabled)

Global Options

• --help – Show help for a command
• --version – Show CLI version

Environment Variables:

• ADK_DEBUG_NEST=1 – Enable detailed NestJS framework logging
• ADK_VERBOSE=1 – Enable verbose output (same as --verbose)