CLI reference

Complete reference for every command in Agents CLI in Gemini 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 -i    Create a new agent project interactively
  agents-cli create my-agent -y    Create with defaults (adk_python, agent_runtime)
  agents-cli playground            Start the local playground
  agents-cli eval run              Run agent inference and grade the traces
  agents-cli scaffold enhance .    Add deployment/CI-CD to a project
  agents-cli deploy                Deploy the agent

agents-cli [OPTIONS] COMMAND [ARGS]...

Option	Type	Description	Default
--version	boolean	Show the version and exit.	Sentinel.UNSET

agents-cli build#

Build the agent binary.

agents-cli build [OPTIONS]

Option	Type	Description	Default
--output, -o	text	Path for the compiled binary.	bin/agent

agents-cli create#

Create GCP-based AI agent projects from templates.

Also available as agents-cli scaffold create.

agents-cli create [OPTIONS] [PROJECT_NAME]

Option	Type	Description	Default
--root-agent-name	text	ADK name of the root agent. Defaults to the project name coerced to an identifier; set it when the agent must be named something else.
--agent, -a	text	Template identifier to use. Can be a local agent name (e.g., chat_agent), a local path (local@/path/to/template), or a remote Git URL. Both shorthand (e.g., github.com/org/repo/path@main) and full URLs from your browser (e.g., https://github.com/org/repo/tree/main/path) are supported. A remote template whose manifest.yaml declares language: go renders on adk_go. Lists available local templates if omitted.	Sentinel.UNSET
--output-dir, -o	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)	GEMINI.md
--base-template, -bt	text	Base template to use (overrides template default, only for remote templates)	Sentinel.UNSET
--cloud-run-identity-default	choice (agent_identity, service_account)	Whether this project's Cloud Run services run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-runtime-identity-default	choice (agent_identity, service_account)	Whether this project's Agent Runtime agents run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-gateway / --no-agent-gateway	boolean	Make the Dockerfile Agent Gateway-ready by trusting the gateway's root CA (Agent Runtime only). Required before agents-cli deploy --agent-gateway-egress
--bq-analytics	boolean	Include BigQuery Agent Analytics Plugin for observability
--agent-directory, -dir	text	Name of the agent directory (overrides template default)	Sentinel.UNSET
--deployment-target, -d	choice (agent_runtime, cloud_run, gke, none)	Deployment target name	Sentinel.UNSET
--cicd-runner	choice (google_cloud_build, github_actions, skip)	CI/CD runner to use	Sentinel.UNSET
--prototype, -p	boolean	Create minimal project without CI/CD or Terraform infrastructure
--session-type	choice (in_memory, cloud_sql, agent_platform_sessions)	Type of session storage to use	Sentinel.UNSET
--debug	boolean	Enable debug logging	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use
--auto-approve, --yes, -y	boolean	Non-interactive: skip prompts and use defaults
--region	text	GCP region for deployment (default: us-east1)
-s, --skip-checks	boolean	Skip verification checks for GCP and Gemini platform
-ag, --agent-garden	boolean	Deployed from Agent Garden - customizes welcome messages
--adk	boolean	Quickstart mode: adk_python + agent_runtime + prototype, skips prompts

agents-cli deploy#

Deploy the agent.

Dispatches by deployment target configured in agents-cli-manifest.yaml:
  agent_runtime → Agent Runtime in Gemini platform
  cloud_run    → gcloud run deploy
  gke          → terraform + docker build + kubectl apply

Pass --deployment-target to override the manifest, or to deploy without a
manifest (e.g. from a built container or CI):
  agents-cli deploy --deployment-target cloud_run

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

agents-cli deploy [OPTIONS]

Option	Type	Description	Default
--project	text	GCP project ID.
--region	text	GCP region.
--deployment-target, -d	choice (agent_runtime, cloud_run, gke)	Deployment target. Overrides agents-cli-manifest.yaml and lets deploy run without a manifest.
--secrets, --update-secrets	text	Comma-separated ENV=SECRET or ENV=SECRET:VERSION pairs (Agent Runtime, Cloud Run).
--agent-identity / --no-agent-identity	boolean	Enable or disable Agent Identity. Passing neither leaves an existing agent's identity untouched (on update) or follows the project's identity default in agents-cli-manifest.yaml (on create).
--env-vars, --update-env-vars	text	Comma-separated KEY=VALUE env vars.
--iap	boolean	Enable Identity-Aware Proxy (Cloud Run).
--port	integer	Container port (Cloud Run / Agent Runtime).
--framework	text	Framework the deployed container implements (Agent Runtime only). Sets agent_framework on the Agent Runtime resource, which the Google Cloud console reads to pick a playground. The API owns the accepted set and quietly falls back to 'custom' for anything else.	the framework recorded in agents-cli-manifest.yaml
--memory	text	Memory limit (Agent Runtime, Cloud Run). Default: 4Gi.
--cpu	text	CPU limit (Agent Runtime, Cloud Run). Default: 1.
--min-instances	integer	Minimum number of instances (Agent Runtime, Cloud Run). Default: 0.
--max-instances	integer	Maximum number of instances (Agent Runtime, Cloud Run). Default: 10.
--concurrency	integer	Concurrent requests per container (Agent Runtime, Cloud Run). Default: 8.
--timeout	integer range (between 1 and 3600)	Request timeout in seconds (Cloud Run). Raise it for requests or connections that outlive Cloud Run's 300s default, which a new service gets. Left unset, an existing service keeps the timeout it has.
--service-account	text	Service account email.
--service-name	text	Override the deployed service name (Cloud Run service or Agent Runtime display name); defaults to the project name. Not supported for GKE. If you override it, consider updating your Terraform and CI (if present) — they derive resource names from the project name.
--image	text	Prebuilt container image URI. Skips the source build. On Agent Runtime the image must be in Artifact Registry, readable by the Agent Runtime service agent.
--build-args	text	Comma-separated KEY=VALUE args passed to the container image build (Agent Runtime).
--labels, --update-labels	text	Comma-separated KEY=VALUE resource labels to add or update (Agent Runtime, Cloud Run). Additive: adds/updates the labels you name; labels you don't name are preserved.
--remove-labels	text	Comma-separated label KEYs to remove (Agent Runtime, Cloud Run). Keys that don't exist are ignored. A key can't appear in both --labels and --remove-labels. Cannot be combined with --clear-labels.
--clear-labels	boolean	Remove all resource labels (Agent Runtime, Cloud Run). Combine with --labels to replace the label set; the clear is applied first. Cannot be combined with --remove-labels.
--cluster-name	text	Cluster name (GKE).
--dry-run, --dryrun, -n	boolean	Print what would be executed without running it. For Agent Runtime, Cloud Run and GKE, also run read-only Google Cloud checks.
--list	boolean	List existing deployments and exit.
--no-wait	boolean	Start the deployment and return immediately.
--update-only	boolean	Update an existing deployment, and fail if there is none to update instead of creating one (Agent Runtime).
--status	boolean	Check the status of a pending --no-wait deployment.
--interactive, -i	boolean	Enable interactive prompts for underlying tooling (gcloud, etc).
--no-confirm-project	boolean	Skip project confirmation prompt.
--network-attachment	text	Network attachment resource name for PSC interface (Agent Runtime). Enables private VPC connectivity. Format: projects/PROJECT/regions/REGION/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).
--agent-gateway-egress	text	Full resource name of an existing Agent Gateway to route the agent's outbound traffic through (Agent Runtime). The gateway must have governedAccessPath=AGENT_TO_ANYWHERE. Pass an empty value to unbind. Omit the flag to leave the current binding alone.
--agent-gateway-ingress	text	Full resource name of an existing Agent Gateway to route the agent's inbound traffic through (Agent Runtime). The gateway must have governedAccessPath=CLIENT_TO_AGENT. Pass an empty value to unbind. Omit the flag to leave the current binding alone.
--key	text	Cloud KMS key for customer-managed encryption (Agent Runtime). Format: projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/KEY. Set on create only; cannot be changed later.
--ingress	choice (all, internal, internal-and-cloud-load-balancing)	Ingress traffic allowed to the service (Cloud Run).

agents-cli eval#

Evaluate agents and compare results.

Core:
  run       Chain generate + grade in one command
  generate  Run agent inference over eval cases
  grade     Grade generated traces
  compare   Compare two eval result JSON files
  metric    Discover and manage evaluation metrics

Advanced (experimental):
  dataset   Synthesize multi-turn eval traces (user simulation)
  analyze   Analyze failure clusters from results
  optimize  Optimize agent prompts using the GEPA framework
  submit    Submit an E2E cloud-side evaluation run on the Eval Service in Gemini platform
  results   Fetch results from a completed cloud evaluation run

agents-cli eval [OPTIONS] COMMAND [ARGS]...

agents-cli eval analyze

[Experimental] Analyze failure clusters from an evaluation run result JSON file. Results are always saved to a file.

agents-cli eval analyze [OPTIONS]

Option	Type	Description	Default
--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	choice (json, html)	Format of the saved output file.	json
--project	text	GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.

agents-cli eval compare

Compare two eval result JSON files.

Reads BASELINE and CANDIDATE JSON files and produces a diff. No subprocess calls — purely in-process comparison.

agents-cli eval compare [OPTIONS] BASELINE CANDIDATE

agents-cli eval dataset

[Experimental] Manage evaluation traces.

agents-cli eval dataset [OPTIONS] COMMAND [ARGS]...

agents-cli eval dataset synthesize

[Experimental] 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`)

agents-cli eval dataset synthesize [OPTIONS]

Option	Type	Description	Default
--count, -n	integer range (1 and above)	Number of conversation scenarios to generate.	3
--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.8-flash.
--max-turns	integer range (1 and above)	Maximum conversation turns per scenario during user simulation.	5
--output, -o	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.

agents-cli eval generate

Generate agent traces by running inference over eval cases.

Reads an evaluation dataset and runs the ADK agent over each case, writing populated traces (agent responses + tool calls) ready for downstream scoring with agents-cli eval grade. Eval cases run in parallel.

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).

By default, tries to run the agent in a local HTTP server (project's fast_api_app.py if it exists, or adk api_server). Pass --url to run against an already-running or deployed agent instead.

For Live (bidi) agents, pass --mode adk_live to run each case over ADK's /run_live WebSocket. Author user-only turns: the agent generates every reply. See /google-agents-cli-eval for details.

Example:
  agents-cli eval generate --dataset eval_cases.json --output artifacts/traces/
  agents-cli eval generate --url https://my-agent.run.app --app-name app
  agents-cli eval generate --mode adk_live
  agents-cli eval generate --mode adk_live --url https://my-live-agent.run.app --app-name app

agents-cli eval generate [OPTIONS]

Option	Type	Description	Default
--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 or eval/datasets/basic-dataset.json' (the file scaffolded by agents-cli create).
--output, -o	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.
--url	text	URL of a running ADK agent to run inference against, e.g. a deployed Cloud Run / GKE URL or a locally-running server. When omitted, agents-cli runs the agent in a local server. Eval cases run in parallel.
--mode	choice (adk, adk_live)	Protocol used to run each case: 'adk' or 'adk_live'. Works locally and with --url.	adk
--app-name	text	Agent app name to use in the ADK URL path (/apps/<app-name>/users/...). Only used when --url is set. Defaults to the project's app name.
--concurrency	integer range (1 and above)	Number of eval cases dispatched in parallel. Each case runs in its own session. Defaults to min(32, number of CPU cores), falling back to 4 if that cannot be determined.
--header, -H	text	Custom HTTP header (format: 'Key: Value'). Repeatable. Overrides auto-detected auth.	Sentinel.UNSET

agents-cli eval grade

Score populated agent traces against one or more metrics.

agents-cli eval grade [OPTIONS]

Option	Type	Description	Default
--traces	path	File or directory of populated traces JSON (output of eval generate or eval dataset synthesize).	Sentinel.UNSET
--output	directory	Directory to save evaluation results and artifacts.	Sentinel.UNSET
--metrics	text	Comma-separated list of metrics to evaluate (e.g., 'final_response_quality,grounding').	Sentinel.UNSET
--config	file	Path to a JSON or YAML file containing metrics to run and custom metrics configuration.	Sentinel.UNSET
--project	text	GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region	text	GCP region for the Eval Service in Gemini platform. Defaults to 'global'.
--qps	float range (0 and above)	Metric computations dispatched per second. Raise it when your metrics are cheap or your judge reuses one client; lower it when the judge model or the eval service rate-limits you.	15.0
--fail-under	text	Fail (exit 1) when METRIC's mean score is below SCORE, in that metric's own scale (0-1 for built-ins, 1-5 for the scaffolded judge). Repeatable, one metric each. Overrides that metric's 'thresholds' entry in the eval config. Errored cases always fail the run.	Sentinel.UNSET

agents-cli eval metric

Discover and manage evaluation metrics.

agents-cli eval metric [OPTIONS] COMMAND [ARGS]...

agents-cli eval metric list

List available out-of-the-box (OOTB) evaluation metrics.

agents-cli eval metric list [OPTIONS]

agents-cli eval optimize

[Experimental] 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.

agents-cli eval optimize [OPTIONS]

Option	Type	Description	Default
--dataset	text	Path to an EvaluationDataset JSON file. Overrides datasets in the config file.	Sentinel.UNSET
--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.

agents-cli eval results

[Experimental] Fetch results from a completed cloud evaluation run.

agents-cli eval results [OPTIONS]

Option	Type	Description	Default
--run-id	text	Evaluation run resource ID/name.	required
--output	directory	Directory to save evaluation results and artifacts.	Sentinel.UNSET
--project	text	GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region	text	GCP region for the Eval Service in Gemini platform. Defaults to 'global'.

agents-cli eval 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

agents-cli eval run [OPTIONS]

Option	Type	Description	Default
--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 for grading. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region	text	GCP region for the Eval Service in Gemini platform (grading). Inference reads GOOGLE_CLOUD_LOCATION from the agent's .env.
--url	text	URL of a running ADK agent to run inference against instead of loading the local project's agent in-process. Forwarded to eval generate.
--mode	choice (adk, adk_live)	Protocol used to evaluate the agent: 'adk' or 'adk_live'. Forwarded to eval generate.	adk
--app-name	text	Agent app name to use in the ADK URL path. Defaults to the project's app name. Forwarded to eval generate.
--concurrency	integer range (1 and above)	Number of eval cases dispatched in parallel. Forwarded to eval generate.	number of CPU cores
--header, -H	text	Custom HTTP header (format: 'Key: Value'). Repeatable. Forwarded to eval generate.	Sentinel.UNSET
--qps	float range (0 and above)	Metric computations dispatched per second. Raise it when your metrics are cheap or your judge reuses one client; lower it when the judge model or the eval service rate-limits you.	15.0
--fail-under	text	Fail (exit 1) when METRIC's mean score is below SCORE, in that metric's own scale (0-1 for built-ins, 1-5 for the scaffolded judge). Repeatable, one metric each. Overrides that metric's 'thresholds' entry in the eval config. Errored cases always fail the run.	Sentinel.UNSET

agents-cli eval submit

[Experimental] Submit an E2E cloud-side evaluation run on the Eval Service in Gemini platform.

agents-cli eval submit [OPTIONS]

Option	Type	Description	Default
--resource-name	text	Resource name of the deployment on Agent Runtime in Gemini platform (e.g. projects/.../locations/.../reasoningEngines/...).	Sentinel.UNSET
--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').	Sentinel.UNSET
--config	file	Path to a JSON or YAML file containing metrics to run and custom metrics configuration.	Sentinel.UNSET
--project	text	GCP project ID. Overrides GOOGLE_CLOUD_PROJECT and ADC.
--region	text	GCP region for the Eval Service in Gemini platform. Defaults to 'global'.

agents-cli extension#

Manage agents-cli extensions (experimental).

Experimental: the manifest schema and the command surface may still change in a breaking way. Pin the CLI version if you depend on either.

Subcommands:
  add     Add an extension from a git reference or local path
  list    List active extensions and the commands they contribute
  update  Advance extension pins and replace their skills
  remove  Remove an installed extension

agents-cli extension [OPTIONS] COMMAND [ARGS]...

agents-cli extension add

Add an extension from a git reference or local path.

agents-cli extension add [OPTIONS] REFERENCE

Option	Type	Description	Default
--global	boolean	Install for all projects (user scope, global/org-wide). Default is project scope (committed to this repo only), so the extension cannot affect your other projects.
--ref	text	Pin a branch, tag, or SHA. For a first-party extension, :latest pins the latest release.
--interactive, -i	boolean	Enable interactive confirmation prompt.
-y, --yes, --auto-approve	boolean	Skip confirmation prompt.

agents-cli extension list

List active extensions and the commands they contribute.

agents-cli extension list [OPTIONS]

agents-cli extension remove

Remove an installed extension (project scope first, then user scope).

agents-cli extension remove [OPTIONS] NAME

Option	Type	Description	Default
--global	boolean	Remove the user-scope install only.
--interactive, -i	boolean	Enable interactive confirmation prompt.
-y, --yes, --auto-approve	boolean	Skip confirmation prompt.

agents-cli extension update

Advance extension pins and replace their skills.

Updates all if NAME omitted.

agents-cli extension update [OPTIONS] [NAME]

Option	Type	Description	Default
--to	text	Re-pin NAME to this branch, tag, or SHA. For first-party extensions, :latest pins the latest release, and works without NAME.
--interactive, -i	boolean	Enable interactive confirmation prompt.
-y, --yes, --auto-approve	boolean	Skip confirmation prompt.

agents-cli info#

Show project configuration, paths, and CLI version.

agents-cli info [OPTIONS]

Option	Type	Description	Default
--json	boolean	Output as JSON.

agents-cli infra#

Provision infrastructure for your agent project.

Subcommands:
  single-project  Optional — custom infrastructure for a single GCP project
  show            Show what single-project provisioned
  cicd            Set up CI/CD pipelines and multi-environment infrastructure

agents-cli infra [OPTIONS] COMMAND [ARGS]...

agents-cli infra 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.

agents-cli infra cicd [OPTIONS]

Option	Type	Description	Default
--dev-project	text	Development project ID	Sentinel.UNSET
--staging-project	text	Staging project ID	Sentinel.UNSET
--prod-project	text	Production project ID	Sentinel.UNSET
--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)	Sentinel.UNSET
--repository-name	text	Repository name (optional)	Sentinel.UNSET
--repository-owner	text	Repository owner (optional, defaults to current GitHub user)
--host-connection-name	text	Host connection name (optional)	Sentinel.UNSET
--github-pat	text	GitHub Personal Access Token for programmatic auth	Sentinel.UNSET
--github-app-installation-id	text	GitHub App Installation ID for programmatic auth	Sentinel.UNSET
--local-state	boolean	Use local Terraform state instead of remote GCS backend (defaults to remote)
--debug	boolean	Enable debug logging	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use.
--create	boolean	Create a new GitHub repository (default: use existing).
--cicd-runner	choice (google_cloud_build, github_actions)	CI/CD runner to use	Sentinel.UNSET
--apply	boolean	Apply changes. Without this flag, only a plan is shown.
--force-bucket, --force	boolean	Allow usage of a terraform config bucket that exists in a different GCP project. By default, this is disallowed to guard against bucket squatting attacks.

agents-cli infra show

Show the outputs of the single-project Terraform root.

Reads the values `agents-cli infra single-project --apply` provisioned —
service account emails, bucket names, and the deployed resource names for
the project's deployment target — without the caller having to know where
the scaffold puts the Terraform root.

Values Terraform marked sensitive are redacted; pass --include-sensitive to
print them.

agents-cli infra show [OPTIONS]

Option	Type	Description	Default
--json	boolean	Output as JSON.
--include-sensitive	boolean	Include values Terraform marked sensitive, in cleartext.

agents-cli infra 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.

agents-cli infra single-project [OPTIONS]

Option	Type	Description	Default
--project	text	GCP project ID.
--apply	boolean	Apply changes. Without this flag, only a plan is shown.

agents-cli install#

Install project dependencies.

agents-cli install [OPTIONS]

Option	Type	Description	Default
--clean	boolean	Clean and fix the uv virtual environment. (For example, if the project folder is moved or renamed).	Sentinel.UNSET
--locked	boolean	Assert that uv.lock is up to date with pyproject.toml; fail instead of updating it.	Sentinel.UNSET

agents-cli lint#

Run code quality checks.

agents-cli lint [OPTIONS]

Option	Type	Description	Default
--fix	boolean	Auto-fix linting issues.
--mypy	boolean	Also run mypy type checking. (Python only)
--skip-codespell	boolean	Skip codespell spell checking. (Python only)
--skip-ty	boolean	Skip ty type checking. (Python only)

agents-cli login#

Authenticate with Google Cloud or AI Studio. Requires --interactive (-i).

agents-cli login [OPTIONS]

Option	Type	Description	Default
--interactive, -i	boolean	Enable interactive authentication (required for login).
--status	boolean	Show authentication status.

agents-cli playground#

Start the local agent playground.

agents-cli playground [OPTIONS]

Option	Type	Description	Default
--port	integer	Port for the playground server.	8080
--host	text	Host the server binds to.	127.0.0.1
--reload_agents / --no-reload_agents	boolean	Enable / disable live reload when agent code changes.	True
--otel-to-cloud	boolean	Export OpenTelemetry traces/logs to Google Cloud.

agents-cli publish#

Publish agents to various targets.

Subcommands:
  gemini  Register a deployed agent with Gemini

agents-cli publish [OPTIONS] COMMAND [ARGS]...

agents-cli publish gemini

Register a deployed agent with Gemini.

All required parameters must be supplied as flags in programmatic mode. Pass --interactive to be guided through missing values interactively.

Use --list to list Gemini apps in the current project:
  agents-cli publish gemini --list

agents-cli publish gemini [OPTIONS]

Option	Type	Description	Default
--agent-runtime-id	text	Resource name of the deployment on Agent Runtime in Gemini platform (e.g., projects/.../reasoningEngines/...). If not provided, reads from deployment_metadata.json.	Sentinel.UNSET
--metadata-file	text	Path to deployment metadata file (default: deployment_metadata.json).
--gemini-app-id	text	Gemini 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 the GEMINI_APP_ID env var.	Sentinel.UNSET
--display-name	text	Display name for the agent.	Sentinel.UNSET
--description	text	Description of the agent.	Sentinel.UNSET
--tool-description	text	Description of what the tool does.	Sentinel.UNSET
--project-id, --project	text	GCP project ID (extracted from agent-runtime-id if not provided).	Sentinel.UNSET
--authorization-id	text	OAuth authorization resource name (e.g., projects/{project_number}/locations/global/authorizations/{auth_id}).	Sentinel.UNSET
--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.	Sentinel.UNSET
--deployment-target	choice (agent_runtime, cloud_run, gke)	Deployment target (agent_runtime, cloud_run, or gke).	Sentinel.UNSET
--project-number	text	GCP project number. Used as default when prompting for the Gemini app.	Sentinel.UNSET
--registration-type	choice (a2a, adk)	Registration type: 'a2a' for A2A agents (requires agent card URL), 'adk' for ADK agents on Agent Runtime (requires an Agent Runtime ID). If not provided, auto-detected from metadata or prompted.	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use.
--list	boolean	List Gemini apps in the current project and exit.

agents-cli 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. A plain run
starts a one-off server and shuts it down when it finishes; pass
--start-server to keep the server running in the background instead.
Once a server is running, later plain runs reuse it (and leave it
running), so repeated requests are faster. Stop a persistent server with
--stop-server. After 30 minutes idle, the next request restarts it.

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 in Gemini platform)
  adk_live  ADK bidi WebSocket (/run_live), for Live and voice agents

Local runs default to adk. Use --mode adk_live to talk to a Live (Voice)
agent, locally or against any deployment target:

  agents-cli run "What's the weather?" --mode adk_live
  agents-cli run "..." --mode adk_live --url https://my-live-agent.run.app --app-name app

Supports --file for multimodal input and --session-id for
conversation continuity. A local session lives in the running server's
memory, so keep the server alive with --start-server to resume it
across separate runs.

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.

agents-cli run [OPTIONS] MESSAGE

Option	Type	Description	Default
--url	text	URL of a remote agent to query. If specified, no local server is started.
--mode	choice (a2a, adk, adk_live)	Protocol used to talk to the agent: 'a2a', 'adk' (SSE), or 'adk_live' (bidi WebSocket). Required with --url; local runs default to 'adk'.
--app-name	text	Agent name for remote ADK SSE / A2A endpoints. Defaults to the local project's app name; specify to query a different agent or to run from outside a project.
--file, -f	path	Attach a file (image, PDF, audio, video). Repeatable.	Sentinel.UNSET
--session-id	text	Resume an existing session. A local session lives in the running server's memory — keep the server alive with --start-server to resume it across runs.
--header, -H	text	Custom HTTP header (format: 'Key: Value'). Repeatable. Overrides auto-detected auth.	Sentinel.UNSET
--start-server	boolean	Keep the local server running after execution. The server persists until stopped with --stop-server, giving subsequent run requests less overhead and keeping in-memory sessions alive between runs.
--stop-server	boolean	Stop the local background server and exit.
--otel-to-cloud	boolean	Export OpenTelemetry traces/logs to Google Cloud. Takes effect when the local server starts; ignored with --url.
--verbose, -v	boolean	Print full JSON event payloads.

agents-cli 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

agents-cli scaffold [OPTIONS] COMMAND [ARGS]...

agents-cli scaffold create

Create GCP-based AI agent projects from templates.

Also available as agents-cli create.

agents-cli scaffold create [OPTIONS] [PROJECT_NAME]

Option	Type	Description	Default
--root-agent-name	text	ADK name of the root agent. Defaults to the project name coerced to an identifier; set it when the agent must be named something else.
--agent, -a	text	Template identifier to use. Can be a local agent name (e.g., chat_agent), a local path (local@/path/to/template), or a remote Git URL. Both shorthand (e.g., github.com/org/repo/path@main) and full URLs from your browser (e.g., https://github.com/org/repo/tree/main/path) are supported. A remote template whose manifest.yaml declares language: go renders on adk_go. Lists available local templates if omitted.	Sentinel.UNSET
--output-dir, -o	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)	GEMINI.md
--base-template, -bt	text	Base template to use (overrides template default, only for remote templates)	Sentinel.UNSET
--cloud-run-identity-default	choice (agent_identity, service_account)	Whether this project's Cloud Run services run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-runtime-identity-default	choice (agent_identity, service_account)	Whether this project's Agent Runtime agents run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-gateway / --no-agent-gateway	boolean	Make the Dockerfile Agent Gateway-ready by trusting the gateway's root CA (Agent Runtime only). Required before agents-cli deploy --agent-gateway-egress
--bq-analytics	boolean	Include BigQuery Agent Analytics Plugin for observability
--agent-directory, -dir	text	Name of the agent directory (overrides template default)	Sentinel.UNSET
--deployment-target, -d	choice (agent_runtime, cloud_run, gke, none)	Deployment target name	Sentinel.UNSET
--cicd-runner	choice (google_cloud_build, github_actions, skip)	CI/CD runner to use	Sentinel.UNSET
--prototype, -p	boolean	Create minimal project without CI/CD or Terraform infrastructure
--session-type	choice (in_memory, cloud_sql, agent_platform_sessions)	Type of session storage to use	Sentinel.UNSET
--debug	boolean	Enable debug logging	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use
--auto-approve, --yes, -y	boolean	Non-interactive: skip prompts and use defaults
--region	text	GCP region for deployment (default: us-east1)
-s, --skip-checks	boolean	Skip verification checks for GCP and Gemini platform
-ag, --agent-garden	boolean	Deployed from Agent Garden - customizes welcome messages
--adk	boolean	Quickstart mode: adk_python + agent_runtime + prototype, skips prompts

agents-cli scaffold enhance

Enhance your existing project with deployment, CI/CD, or RAG scaffolding.

Applies a template in-place, adding infrastructure files without touching your agent logic. It always enhances the current directory.

TEMPLATE_PATH says which template to apply, not which project to enhance. It defaults to the current directory, which re-renders the scaffolding from the base template and puts your files back on top.

If the project has an agents-cli-manifest.yaml, the template recorded there is re-applied and TEMPLATE_PATH is ignored. Pass a local directory or a remote spec (org/repo@tag) for a project agents-cli did not create. Your files the template replaces, such as pyproject.toml, are moved to .agents-cli-original/ so you can port them; the rest stay where they are.

--base-template is separate. It names a base template this CLI ships, which sits underneath whatever TEMPLATE_PATH supplies.

Use --dry-run to preview changes before applying them.

agents-cli scaffold enhance [OPTIONS] [TEMPLATE_PATH]

Option	Type	Description	Default
--name, -n	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)	GEMINI.md
--base-template, -bt	text	Base template to use (overrides template default, only for remote templates)	Sentinel.UNSET
--cloud-run-identity-default	choice (agent_identity, service_account)	Whether this project's Cloud Run services run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-runtime-identity-default	choice (agent_identity, service_account)	Whether this project's Agent Runtime agents run as their own Agent Identity principal (agent_identity) or as a service account (service_account). New projects use agent_identity.
--agent-gateway / --no-agent-gateway	boolean	Make the Dockerfile Agent Gateway-ready by trusting the gateway's root CA (Agent Runtime only). Required before agents-cli deploy --agent-gateway-egress
--bq-analytics	boolean	Include BigQuery Agent Analytics Plugin for observability
--agent-directory, -dir	text	Name of the agent directory (overrides template default)	Sentinel.UNSET
--deployment-target, -d	choice (agent_runtime, cloud_run, gke, none)	Deployment target name	Sentinel.UNSET
--cicd-runner	choice (google_cloud_build, github_actions, skip)	CI/CD runner to use	Sentinel.UNSET
--prototype, -p	boolean	Create minimal project without CI/CD or Terraform infrastructure
--session-type	choice (in_memory, cloud_sql, agent_platform_sessions)	Type of session storage to use	Sentinel.UNSET
--debug	boolean	Enable debug logging	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use
--auto-approve, --yes, -y	boolean	Non-interactive: skip prompts and use defaults
--region	text	GCP region for deployment (default: us-east1)
-s, --skip-checks	boolean	Skip verification checks for GCP and Gemini platform
-ag, --agent-garden	boolean	Deployed from Agent Garden - customizes welcome messages
--adk	boolean	Shortcut for --base-template adk_python
--force	boolean	Force overwrite all files (skip smart-merge comparison)
--dry-run, --dryrun	boolean	Preview changes without applying them (requires saved metadata)
--prefer-new	boolean	Resolve conflicts in favor of the new template version

agents-cli scaffold 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.

Use --force if the merge fails. It overwrites scaffolding files with the new template and keeps agent code and config files. It never removes dependencies or files the new template dropped.

agents-cli scaffold upgrade [OPTIONS] [PROJECT_PATH]

Option	Type	Description	Default
--dry-run, --dryrun	boolean	Preview changes without applying them	Sentinel.UNSET
--auto-approve, --yes, -y	boolean	Auto-apply non-conflicting changes without prompts	Sentinel.UNSET
--interactive, -i	boolean	Enable interactive prompts for human use
--force	boolean	Overwrite scaffolding files with the new template (skip the 3-way merge)
--debug	boolean	Enable debug logging	Sentinel.UNSET

agents-cli 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, Antigravity 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.

agents-cli setup [OPTIONS]

Option	Type	Description	Default
--workspace	boolean	Install to project/workspace scope instead of global. Skills are installed relative to the current directory.
--skip-auth	boolean	Skip the authentication step.
--dry-run, --dryrun	boolean	Show what would be done without making changes.
--dev	boolean	Install as editable from the local repo (for contributors).
--interactive, -i	boolean	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.	Sentinel.UNSET

agents-cli update#

Force reinstall agents skills to all detected coding agents.

Updates all installed skills to their latest versions via npx skills.

agents-cli update [OPTIONS]

Option	Type	Description	Default
--workspace	boolean	Update workspace-level skills instead of global.
--interactive, -i	boolean	Enable interactive confirmation prompt.
-y, --yes, --auto-approve	boolean	Skip confirmation prompt.