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 eval generate Run agent inference over eval cases agents-cli eval grade Grade generated traces agents-cli scaffold enhance . Add deployment/CI-CD to a project 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 agents-cli-manifest.yaml: 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, --dryrun 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.
--network-attachment TEXT Network attachment resource name for PSC
interface (Agent Runtime). Enables private VPC
connectivity. Format: projects/PROJECT/regions/R
EGION/networkAttachments/NAME
--dns-peering-domain TEXT DNS peering domain suffix, e.g. 'my-
internal.corp.' (Agent Runtime, requires
--network-attachment).
--dns-peering-project TEXT Project ID hosting the Cloud DNS managed zone
for DNS peering (Agent Runtime, requires
--network-attachment).
--dns-peering-network TEXT VPC network name in the target project for DNS
peering (Agent Runtime, requires --network-
attachment).
--help Show this message and exit.
eval¶
Evaluate agents and compare results.
Subcommands: generate Run agent inference over eval cases grade Grade generated traces run Chain generate + grade in one command dataset Manage evaluation traces metric Discover and manage evaluation metrics compare Compare two eval result JSON files analyze Analyze loss clusters from results optimize Optimize agent prompts using the GEPA framework submit Submit an E2E cloud-side evaluation run on Vertex AI Eval Service results Fetch results from a completed cloud evaluation run
Usage:
Options:
analyze¶
Analyze failure clusters from an evaluation run result JSON file. Results are always saved to a file.
Usage:
Options:
--eval-result FILE Required. Path to the evaluation results JSON
file. [required]
--top-k INTEGER Optional. Maximum number of loss clusters to
identify.
--metric TEXT Optional. Evaluation metric name to run
analysis against. Currently supported:
multi_turn_task_success,
multi_turn_tool_use_quality
--output FILE Optional. Path where the results should be
saved. Defaults to saving to the 'artifacts'
directory.
--output-format [json|html] Format of the saved output file. [default:
json]
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT
and ADC.
--help Show this message and exit.
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:
dataset¶
Manage evaluation traces.
Usage:
Options:
synthesize¶
Synthesize evaluation traces (eval cases with full agent runs).
Generates synthetic multi-turn conversations by inspecting the project's
ADK agent (read from agent_directory in agents-cli-manifest.yaml) and running it
with a model-based user simulator.
Examples: # Basic — synthesize 3 scenarios with up to 5 turns each: agents-cli eval dataset synthesize
# Custom count, turns, and instruction: agents-cli eval dataset synthesize -n 10 --max-turns 8 \ --instruction "Scenarios where users change destination"
Requires:
- A local ADK agent project with agents-cli-manifest.yaml
- Google Cloud authentication (agents-cli login)
Usage:
Options:
-n, --count INTEGER RANGE Number of conversation scenarios to generate.
[default: 3; x>=1]
--instruction TEXT Natural-language instruction guiding scenario
generation. Example: 'Generate scenarios where
the user changes their mind.'
--environment-context TEXT Environment context injected into each scenario.
Example: 'Today is Monday. Flights to Paris are
available.'
--model TEXT Optional. Custom model used for scenario
generation.Example: gemini-3-flash-preview.
--max-turns INTEGER RANGE Maximum conversation turns per scenario during
user simulation. [default: 5; x>=1]
-o, --output TEXT Output path for the synthesized traces. If an
existing directory is given, a timestamped file
is written inside it; otherwise the value is
treated as a file path. Defaults to a
timestamped file under 'artifacts/traces/' so
that `agents-cli eval grade` can consume it
directly.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT
and ADC.
--region TEXT GCP region for the Vertex eval service. Defaults
to 'global'.
--help Show this message and exit.
generate¶
Generate agent traces by running inference over eval cases.
Reads an evaluation dataset, runs the project's local ADK agent (read from
agent_directory in agents-cli-manifest.yaml) over each eval case, and writes the
populated traces (agent responses + tool calls) ready for downstream
scoring with agents-cli eval grade.
Each eval case must provide one of:
* a top-level prompt field (single user message), or
* agent_data whose turns end with a user message — for continued
conversations where the next agent response should be appended
(the "N+1" pattern).
Example: agents-cli eval generate --dataset eval_cases.json --output artifacts/traces/
Usage:
Options:
--dataset TEXT Path to a JSON dataset file of eval cases ready for
inference. Each case must provide one of: a top-level
'prompt' field (single user message), or 'agent_data'
whose turns end with a user message (continued
conversation; appends the next agent response). Defaults
to 'tests/eval/datasets/basic-dataset.json' (the file
scaffolded by `agents-cli create`).
-o, --output TEXT Output path for the populated traces. If an existing
directory is given, a timestamped file is written inside
it; otherwise the value is treated as a file path.
Defaults to a timestamped file under 'artifacts/traces/'
so that `agents-cli eval grade` can consume it directly.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region TEXT GCP region. Overrides agents-cli-manifest.yaml region and
the GOOGLE_CLOUD_LOCATION env var.
--help Show this message and exit.
grade¶
Score populated agent traces against one or more metrics.
Usage:
Options:
--traces PATH File or directory of populated traces JSON (output of
`eval generate` or `eval dataset synthesize`).
--output DIRECTORY Directory to save evaluation results and artifacts.
--metrics TEXT Comma-separated list of metrics to evaluate (e.g.,
'final_response_quality,grounding').
--config FILE Path to a JSON or YAML file containing metrics to run
and custom metrics configuration.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region TEXT GCP region for the Vertex eval service. Defaults to
'global'.
--help Show this message and exit.
metric¶
Discover and manage evaluation metrics.
Usage:
Options:
list¶
List available out-of-the-box (OOTB) evaluation metrics.
Usage:
Options:
optimize¶
Optimize agent prompts using the GEPA framework.
This command runs 'adk optimize' under the hood to automatically improve your agent's instructions by iteratively refining the prompt.
How it works: - --dataset: Path to a JSON file in EvaluationDataset format. If not provided, it uses values from your config file. - --target-metric: The name of the evaluation metric to optimize for. If not provided, it uses values from your config file. - --config: Optional JSON file for advanced configuration. It can include: - eval_config (ADK EvalConfig) - train_dataset (Path to EvaluationDataset JSON file or dict in EvaluationDataset format) - validation_dataset (Path to EvaluationDataset JSON file or dict in EvaluationDataset format) - optimizer_config (ADK GEPARootAgentPromptOptimizerConfig) - log_level (string, e.g., 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'). Default is 'WARNING'. - print_detailed_results (boolean). Set to true to enable printing detailed results. Default is false. - Default Paths: By default, it looks for a JSON config file in tests/eval/optimization_config.json.
Usage:
Options:
--dataset TEXT Path to an EvaluationDataset JSON file. Overrides
datasets in the config file.
--target-metric TEXT The evaluation metric to optimize for. Overrides
evaluation settings in the config file.
--config TEXT Path to a combined JSON config file for advanced
settings.
--help Show this message and exit.
results¶
Fetch results from a completed cloud evaluation run.
Usage:
Options:
--run-id TEXT Evaluation run resource ID/name. [required]
--output DIRECTORY Directory to save evaluation results and artifacts.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region TEXT GCP region for the Vertex eval service. Defaults to
'global'.
--help Show this message and exit.
run¶
Chain eval generate and eval grade in one command.
Thin alias for the common path: runs inference over the dataset to produce
traces in the default artifacts/traces/ directory, then grades those
traces and writes results.
For custom intermediate trace locations, use the two-step form
(eval generate then eval grade) instead.
Example: agents-cli eval run --dataset eval_cases.json --metrics final_response_quality
Usage:
Options:
--dataset TEXT Path to a JSON dataset file of eval cases ready for
inference. Forwarded to `eval generate`. Defaults to the
file scaffolded by `agents-cli create`.
--output DIRECTORY Directory to save final evaluation results and
artifacts. Forwarded to `eval grade`. Defaults to
`artifacts/grade_results/`.
--metrics TEXT Comma-separated list of metrics to evaluate (e.g.,
'final_response_quality,grounding'). Forwarded to `eval
grade`.
--config FILE Path to a JSON or YAML file containing metrics to run
and custom metrics configuration. Forwarded to `eval
grade`.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region TEXT GCP region. Overrides agents-cli-manifest.yaml region
and the GOOGLE_CLOUD_LOCATION env var.
--help Show this message and exit.
submit¶
Submit an E2E cloud-side evaluation run on Vertex AI Eval Service.
Usage:
Options:
--resource-name TEXT Agent engine resource name (e.g.
projects/.../locations/.../reasoningEngines/...).
--dataset FILE Path to evaluation dataset file (JSON trace etc.).
[required]
--dest TEXT GCS output bucket URI prefix staging path (e.g.,
gs://my-bucket). [required]
--metrics TEXT Comma-separated list of metrics to evaluate (e.g.,
'final_response_quality,grounding').
--config FILE Path to a JSON or YAML file containing metrics to run
and custom metrics configuration.
--project TEXT GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and
ADC.
--region TEXT GCP region for the Vertex eval service. Defaults to
'global'.
--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.
--trace-to-cloud Export traces to Google Cloud Trace.
--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.
--trace-to-cloud Export traces to Google Cloud Trace. Takes effect when
the local server starts; ignored with --url.
-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, --dryrun 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, --dryrun 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 for all detected agents. Use --workspace to install at the project level instead. Use --agent to specify specific coding agents (e.g. --agent claude-code --agent cursor) or 'all'. 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, --dryrun 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.
--agent TEXT Specify the agent to install skills to (e.g. --agent
claude-code --agent cursor). Use 'all' to install for
all supported agents.
--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: