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

```text
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
```

```text title="Usage"
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.

```text title="Usage"
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`.

```text title="Usage"
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.

```text
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
```

```text title="Usage"
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.

```text
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
```

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
agents-cli eval compare [OPTIONS] BASELINE CANDIDATE
```

#### `agents-cli eval dataset`

\[Experimental\] Manage evaluation traces.

```text title="Usage"
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.

```text
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`)
```

```text title="Usage"
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.

```text
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.

```text
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
```

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
agents-cli eval metric [OPTIONS] COMMAND [ARGS]...
```

##### `agents-cli eval metric list`

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

```text title="Usage"
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.

```text
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.
```

```text title="Usage"
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.

```text title="Usage"
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.

```text
Example:
  agents-cli eval run --dataset eval_cases.json --metrics final_response_quality
```

```text title="Usage"
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.

```text title="Usage"
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.

```text
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
```

```text title="Usage"
agents-cli extension [OPTIONS] COMMAND [ARGS]...
```

#### `agents-cli extension add`

Add an extension from a git reference or local path.

```text title="Usage"
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.

```text title="Usage"
agents-cli extension list [OPTIONS]
```

#### `agents-cli extension remove`

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

```text title="Usage"
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.

```text title="Usage"
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. |  |

<div id="cmd-info"></div>

### `agents-cli info`

Show project configuration, paths, and CLI version.

```text title="Usage"
agents-cli info [OPTIONS]
```

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

### `agents-cli infra`

Provision infrastructure for your agent project.

```text
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
```

```text title="Usage"
agents-cli infra [OPTIONS] COMMAND [ARGS]...
```

<div id="setup-cicd"></div>

#### `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.

```text
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.
```

```text title="Usage"
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.

```text
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.
```

```text title="Usage"
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.

```text
By default, runs terraform init + terraform plan to preview changes.
Use --apply to apply the changes.
```

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
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).

```text title="Usage"
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.

```text title="Usage"
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.

```text
Subcommands:
  gemini  Register a deployed agent with Gemini
```

```text title="Usage"
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.

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

```text title="Usage"
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.

```text
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.
```

```text title="Usage"
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.

```text
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
```

```text title="Usage"
agents-cli scaffold [OPTIONS] COMMAND [ARGS]...
```

#### `agents-cli scaffold create`

Create GCP-based AI agent projects from templates.

Also available as `agents-cli create`.

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
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.

```text title="Usage"
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. |  |