CLI Reference¶
Complete reference for every command in Agents CLI in Agent Platform (the agents-cli binary).
agents-cli¶
Agents CLI — Agent Development Lifecycle toolchain.
Build, evaluate, and deploy ADK agents with a single unified CLI.
Quick start: agents-cli setup Install skills to your coding agent agents-cli create my-agent Create a new agent project agents-cli playground Start the local playground agents-cli scaffold enhance . Add deployment/CI-CD to a project agents-cli eval run Run evaluations agents-cli deploy Deploy the agent
Usage:
Options:
cmd-info¶
Show project configuration, paths, and CLI version.
Usage:
Options:
create¶
Create GCP-based AI agent projects from templates.
Usage:
Options:
-a, --agent TEXT Template identifier to use. Can be a local
agent name (e.g., `chat_agent`), a local
path (`local@/path/to/template`), an `adk-
samples` shortcut (e.g., `adk@data-
science`), or a remote Git URL. Both
shorthand (e.g.,
`github.com/org/repo/path@main`) and full
URLs from your browser (e.g., `https://githu
b.com/org/repo/tree/main/path`) are
supported. Lists available local templates
if omitted.
-o, --output-dir PATH Output directory for the project (default:
current directory)
--agent-guidance-filename TEXT Filename for agent guidance (e.g.,
GEMINI.md, CLAUDE.md, AGENTS.md)
-bt, --base-template TEXT Base template to use (overrides template
default, only for remote templates)
--bq-analytics Include BigQuery Agent Analytics Plugin for
observability
-dir, --agent-directory TEXT Name of the agent directory (overrides
template default)
-d, --deployment-target [agent_runtime|cloud_run|gke|none]
Deployment target name
--cicd-runner [google_cloud_build|github_actions|skip]
CI/CD runner to use
-p, --prototype Create minimal project without CI/CD or
Terraform infrastructure
-ds, --datastore [agent_platform_search|agent_platform_vector_search]
Type of datastore to use for data ingestion
--session-type [in_memory|cloud_sql|agent_platform_sessions]
Type of session storage to use
--debug Enable debug logging
-i, --interactive Enable interactive prompts for human use
-y, --auto-approve, --yes Non-interactive: skip prompts and use
defaults
--region TEXT GCP region for deployment (default: us-
east1)
-s, --skip-checks Skip verification checks for GCP and Vertex
AI
-ag, --agent-garden Deployed from Agent Garden - customizes
welcome messages
-k, --google-api-key, --api-key TEXT
Use Google AI Studio API key instead of
Vertex AI. If provided without a value,
generates a .env file with a placeholder.
--adk Quickstart mode: adk + agent_runtime +
prototype, skips prompts
--help Show this message and exit.
data-ingestion¶
Run data ingestion for RAG agents.
For agent_platform_vector_search: submits the ingestion pipeline. For agent_platform_search: syncs the data connector.
Regions: --vector-search-location (defaults to us-central1) sets both the Vector Search collection region and the BQ ingestion dataset region, kept colocated to avoid cross-region data movement.
Usage:
Options:
--project TEXT GCP project ID.
--region TEXT GCP region.
--vector-search-location TEXT Vector Search 2.0 location (defaults to us-
central1). Also sets the BQ ingestion dataset
region to keep it colocated with the
collection.
--collection-id TEXT Collection ID for the data connector.
--remote Submit pipeline to Vertex AI Pipelines
instead of running locally.
--help Show this message and exit.
deploy¶
Deploy the agent.
Dispatches by deployment target configured in pyproject.toml: agent_runtime → Agent Runtime deployment cloud_run → gcloud beta run deploy gke → terraform + docker build + kubectl apply
Use --list to show existing deployments: agents-cli deploy --list
Use --no-wait to start a deployment and return immediately: agents-cli deploy --no-wait
Use --status to check on a --no-wait deployment: agents-cli deploy --status
Usage:
Options:
--project TEXT GCP project ID.
--region TEXT GCP region.
--secrets TEXT Comma-separated ENV=SECRET pairs.
--agent-identity Enable agent identity.
--update-env-vars TEXT Comma-separated KEY=VALUE env vars.
--iap Enable Identity-Aware Proxy (Cloud Run).
--port INTEGER Container port (Cloud Run).
--memory TEXT Memory limit (Cloud Run). Default: 4Gi.
--service-account TEXT Service account email.
--image TEXT Container image URI (Cloud Run / GKE). Skips source
build.
--cluster-name TEXT Cluster name (GKE).
-n, --dry-run Print what would be executed without running it.
--list List existing deployments and exit.
--no-wait Start the deployment and return immediately.
--status Check the status of a pending --no-wait deployment.
-i, --interactive Enable interactive prompts for underlying tooling
(gcloud, etc).
--no-confirm-project Skip project confirmation prompt.
--help Show this message and exit.
eval¶
Evaluate agents and compare results.
Subcommands: run Run agent evaluations compare Compare two eval result JSON files
Usage:
Options:
compare¶
Compare two eval result JSON files.
Reads BASELINE and CANDIDATE JSON files and produces a diff. No subprocess calls — purely in-process comparison.
Usage:
Options:
run¶
Run agent evaluations.
Runs: uv run adk eval ./{agent_dir} EVALSET --config_file_path CONFIG
Usage:
Options:
--evalset TEXT Path to evalset JSON file.
--config TEXT Path to eval config JSON file.
--all Run all eval sets found in tests/eval/evalsets/.
--help Show this message and exit.
infra¶
Provision infrastructure for your agent project.
Subcommands: single-project Optional — custom infrastructure for a single GCP project cicd Set up CI/CD pipelines and multi-environment infrastructure datastore Provision datastore infrastructure for RAG agents
Usage:
Options:
datastore¶
Provision datastore infrastructure for RAG agents.
Reads datastore_type from project config and runs the appropriate Terraform targets to set up the data backend.
Usage:
Options:
setup-cicd¶
Set up CI/CD pipelines and Terraform infrastructure for your agent project.
Provisions GitHub Actions or Cloud Build pipelines with staging and production environments. Requires staging, prod, and CI/CD project IDs as flags. Pass --interactive to be guided through missing values interactively.
By default, runs terraform plan to preview changes. Use --apply to apply. Note: plan mode still writes local config files (env.tfvars, Terraform templates) and verifies cloud prerequisites (GitHub auth, Cloud Build connections) as these are required for an accurate plan.
Usage:
Options:
--dev-project TEXT Development project ID
--staging-project TEXT Staging project ID
--prod-project TEXT Production project ID
--cicd-project TEXT CICD project ID (defaults to prod project if
not specified)
--region TEXT GCP region (auto-detects from Terraform vars
if not specified)
--repository-name TEXT Repository name (optional)
--repository-owner TEXT Repository owner (optional, defaults to
current GitHub user)
--host-connection-name TEXT Host connection name (optional)
--github-pat TEXT GitHub Personal Access Token for
programmatic auth
--github-app-installation-id TEXT
GitHub App Installation ID for programmatic
auth
--local-state Use local Terraform state instead of remote
GCS backend (defaults to remote)
--debug Enable debug logging
-i, --interactive Enable interactive prompts for human use.
--create Create a new GitHub repository (default: use
existing).
--cicd-runner [google_cloud_build|github_actions]
CI/CD runner to use
--apply Apply changes. Without this flag, only a
plan is shown.
--help Show this message and exit.
single-project¶
Provision single-project infrastructure (optional).
Not required for basic deployments — agents-cli deploy works out of the
box using smart defaults (default Compute Engine service account,
on-the-fly resource provisioning). Run this when you need custom setup
such as a dedicated service account, pre-provisioned secrets, or specific
IAM bindings.
By default, runs terraform init + terraform plan to preview changes. Use --apply to apply the changes.
Usage:
Options:
--project TEXT GCP project ID.
--apply Apply changes. Without this flag, only a plan is shown.
--help Show this message and exit.
install¶
Install project dependencies.
Runs: uv sync
Usage:
Options:
--clean Clean and fix the uv virtual environment. (For example, if the
project folder is moved or renamed).
--help Show this message and exit.
lint¶
Run code quality checks.
Runs: uv run ruff check . uv run ruff format . --check uv run codespell (unless --skip-codespell) uv run ty check . (unless --skip-ty) uv run mypy . (if --mypy)
Usage:
Options:
--fix Auto-fix linting issues.
--mypy Also run mypy type checking.
--skip-codespell Skip codespell spell checking.
--skip-ty Skip ty type checking.
--help Show this message and exit.
login¶
Authenticate with Google Cloud or AI Studio. Requires --interactive (-i).
Usage:
Options:
-i, --interactive Enable interactive authentication (required for login).
--status Show authentication status.
--help Show this message and exit.
playground¶
Start the local agent playground.
Usage:
Options:
--port INTEGER Port for the playground server.
--host TEXT Host the server binds to.
--reload_agents / --no-reload_agents
Enable / disable live reload when agent code
changes.
--help Show this message and exit.
publish¶
Publish agents to various targets.
Subcommands: gemini-enterprise Register an Agent Runtime to Gemini Enterprise
Usage:
Options:
gemini-enterprise¶
Register a deployed agent with Gemini Enterprise.
All required parameters must be supplied as flags in programmatic mode. Pass --interactive to be guided through missing values interactively.
\b Use --list to list Gemini Enterprise apps in the current project: agents-cli publish gemini-enterprise --list
Usage:
Options:
--agent-runtime-id TEXT Agent Runtime resource name (e.g.,
projects/.../reasoningEngines/...). If not
provided, reads from
deployment_metadata.json.
--metadata-file TEXT Path to deployment metadata file (default:
deployment_metadata.json).
--gemini-enterprise-app-id TEXT
Gemini Enterprise app full resource name
(e.g., projects/{project_number}/locations/{
location}/collections/{collection}/engines/{
engine_id}). If not provided, the command
will prompt you interactively. Can also be
set via ID or GEMINI_ENTERPRISE_APP_ID env
var.
--display-name TEXT Display name for the agent.
--description TEXT Description of the agent.
--tool-description TEXT Description of what the tool does.
--project-id TEXT GCP project ID (extracted from agent-
runtime-id if not provided).
--authorization-id TEXT OAuth authorization resource name (e.g., pro
jects/{project_number}/locations/global/auth
orizations/{auth_id}).
--agent-card-url TEXT URL to fetch the agent card for A2A agents
(e.g., https://your-
service.run.app/a2a/app/.well-known/agent-
card.json). If provided, registers as an A2A
agent instead of ADK agent.
--deployment-target [agent_runtime|cloud_run|gke]
Deployment target (agent_runtime, cloud_run,
or gke).
--project-number TEXT GCP project number. Used as default when
prompting for Gemini Enterprise
configuration.
--registration-type [a2a|adk] Registration type: 'a2a' for A2A agents
(requires agent card URL), 'adk' for ADK
agents on Agent Runtime (requires agent
engine ID). If not provided, auto-detected
from metadata or prompted.
-i, --interactive Enable interactive prompts for human use.
--list List Gemini Enterprise apps in the current
project and exit.
--help Show this message and exit.
run¶
Run the agent with a single prompt (non-interactive).
MESSAGE is the prompt to send to the agent.
Run from your project directory to query the agent locally. By default, the local server is shut down after the command completes. Use --start-server to keep the server running in the background, which improves efficiency for multiple requests and is required for local sessions. A running server persists until stopped with --stop-server. After 30 minutes idle, any request will restart the server.
Use --url to query a deployed agent instead. Requires --mode to choose the protocol:
a2a A2A protocol adk ADK SSE (/run_sse, or :streamQuery for Agent Runtime)
Supports --file for multimodal input and --session-id for conversation continuity. Local sessions require --start-server.
Binary artifacts (images, audio, files) returned by the agent are saved under '.google-agents-cli/artifacts/' in the project root and listed in an 'Artifacts:' footer at the end of the response. File references returned by URI are not downloaded.
Usage:
Options:
--url TEXT URL of a remote agent to query. If specified, no local
server is started.
--mode [a2a|adk] Protocol for --url queries: 'a2a' or 'adk'. Required when
using --url. Local runs always use ADK SSE.
--app-name TEXT Agent name for remote ADK SSE / A2A endpoints. Defaults
to the local project's agent_directory; specify to query
a different agent or to run from outside a project.
-f, --file PATH Attach a file (image, PDF, audio, video). Repeatable.
--session-id TEXT Resume an existing session/conversation context. Requires
--start-server for local sessions.
-H, --header TEXT Custom HTTP header (format: 'Key: Value'). Repeatable.
Overrides auto-detected auth.
--start-server Keep the local server running after execution. The server
persists until stopped with --stop-server, resulting in
less overhead for subsequent run requests. Sessions
require this flag to persist state.
--stop-server Stop the local background server and exit.
-v, --verbose Print full JSON event payloads.
--help Show this message and exit.
scaffold¶
Scaffold, enhance, and upgrade agent projects.
Subcommands: create Create a new agent project enhance Add deployment target or CI/CD to an existing project upgrade Upgrade project to a newer agents-cli version
Usage:
Options:
create¶
Create GCP-based AI agent projects from templates.
Usage:
Options:
-a, --agent TEXT Template identifier to use. Can be a local
agent name (e.g., `chat_agent`), a local
path (`local@/path/to/template`), an `adk-
samples` shortcut (e.g., `adk@data-
science`), or a remote Git URL. Both
shorthand (e.g.,
`github.com/org/repo/path@main`) and full
URLs from your browser (e.g., `https://githu
b.com/org/repo/tree/main/path`) are
supported. Lists available local templates
if omitted.
-o, --output-dir PATH Output directory for the project (default:
current directory)
--agent-guidance-filename TEXT Filename for agent guidance (e.g.,
GEMINI.md, CLAUDE.md, AGENTS.md)
-bt, --base-template TEXT Base template to use (overrides template
default, only for remote templates)
--bq-analytics Include BigQuery Agent Analytics Plugin for
observability
-dir, --agent-directory TEXT Name of the agent directory (overrides
template default)
-d, --deployment-target [agent_runtime|cloud_run|gke|none]
Deployment target name
--cicd-runner [google_cloud_build|github_actions|skip]
CI/CD runner to use
-p, --prototype Create minimal project without CI/CD or
Terraform infrastructure
-ds, --datastore [agent_platform_search|agent_platform_vector_search]
Type of datastore to use for data ingestion
--session-type [in_memory|cloud_sql|agent_platform_sessions]
Type of session storage to use
--debug Enable debug logging
-i, --interactive Enable interactive prompts for human use
-y, --auto-approve, --yes Non-interactive: skip prompts and use
defaults
--region TEXT GCP region for deployment (default: us-
east1)
-s, --skip-checks Skip verification checks for GCP and Vertex
AI
-ag, --agent-garden Deployed from Agent Garden - customizes
welcome messages
-k, --google-api-key, --api-key TEXT
Use Google AI Studio API key instead of
Vertex AI. If provided without a value,
generates a .env file with a placeholder.
--adk Quickstart mode: adk + agent_runtime +
prototype, skips prompts
--help Show this message and exit.
enhance¶
Enhance your existing project with deployment, CI/CD, or RAG scaffolding.
Applies agents-cli templates in-place to an existing project directory, adding infrastructure files without touching your agent logic.
Run from inside your project directory (pass . as the path) or point to it explicitly. Use --dry-run to preview changes before applying them.
Usage:
Options:
-n, --name TEXT Project name for templating (defaults to
current directory name)
--agent-guidance-filename TEXT Filename for agent guidance (e.g.,
GEMINI.md, CLAUDE.md, AGENTS.md)
-bt, --base-template TEXT Base template to use (overrides template
default, only for remote templates)
--bq-analytics Include BigQuery Agent Analytics Plugin for
observability
-dir, --agent-directory TEXT Name of the agent directory (overrides
template default)
-d, --deployment-target [agent_runtime|cloud_run|gke|none]
Deployment target name
--cicd-runner [google_cloud_build|github_actions|skip]
CI/CD runner to use
-p, --prototype Create minimal project without CI/CD or
Terraform infrastructure
-ds, --datastore [agent_platform_search|agent_platform_vector_search]
Type of datastore to use for data ingestion
--session-type [in_memory|cloud_sql|agent_platform_sessions]
Type of session storage to use
--debug Enable debug logging
-i, --interactive Enable interactive prompts for human use
-y, --auto-approve, --yes Non-interactive: skip prompts and use
defaults
--region TEXT GCP region for deployment (default: us-
east1)
-s, --skip-checks Skip verification checks for GCP and Vertex
AI
-ag, --agent-garden Deployed from Agent Garden - customizes
welcome messages
-k, --google-api-key, --api-key TEXT
Use Google AI Studio API key instead of
Vertex AI. If provided without a value,
generates a .env file with a placeholder.
--adk Shortcut for --base-template adk
--force Force overwrite all files (skip smart-merge
comparison)
--dry-run Preview changes without applying them
(requires saved metadata)
--prefer-new Resolve conflicts in favor of the new
template version
--help Show this message and exit.
upgrade¶
Upgrade project to a newer agents-cli version.
Applies a 3-way merge between the old template, the new template, and your project: unmodified files are auto-updated, your customizations are preserved, and conflicts are surfaced for manual resolution (with --interactive) or kept as-is.
Usage:
Options:
--dry-run Preview changes without applying them
-y, --auto-approve, --yes Auto-apply non-conflicting changes without
prompts
-i, --interactive Enable interactive prompts for human use
--debug Enable debug logging
--help Show this message and exit.
setup¶
Install agents-cli and skills to detected coding agents.
Installs the agents-cli tool (via uv tool install) and detects installed coding agents (Claude Code, Gemini CLI, Cursor, Windsurf, etc.) to install ADK development skills via npx skills.
By default, skills are installed globally. Use --workspace to install at the project level instead. Use --dry-run to preview what would happen without executing. Use --dev to install agents-cli as editable from the local repo (for contributors). Use --interactive / -i to enable interactive authentication if not already logged in.
Usage:
Options:
--workspace Install to project/workspace scope instead of global.
Skills are installed relative to the current
directory.
--skip-auth Skip the authentication step.
--dry-run Show what would be done without making changes.
--dev Install as editable from the local repo (for
contributors).
-i, --interactive Enable interactive authentication prompt if not
already authenticated.
--skills-source TEXT Skills source: local path, GitHub owner/repo, or URL.
Overrides the bundled skills.
--help Show this message and exit.
update¶
Force reinstall agents skills to all detected coding agents.
Updates all installed skills to their latest versions via npx skills.
Usage:
Options: