extension

Extensions — override or extend agents-cli

An extension overrides or adds a built-in command. It's a directory containing an `agents-cli-extension.yaml`, so any git repo can serve as a registry.

Two things you can do: **author** an extension (start ad-hoc in the current repo, publish it later), or **adopt** an existing one.

---

Author an ad-hoc extension (no separate repo)

Drop a single file, `agents-cli-extension.yaml`, at the project root (next to `agents-cli-manifest.yaml`). It's auto-loaded at project scope, so no `extension add` is needed. Commit it and teammates and CI get the same overrides.

Only one, at that exact path, and always project scope. For a second one, or to install a local extension globally, move it into its own directory and `agents-cli extension add local@./path --global`; `#name` picks one out of a directory holding several.

**Publish it for other repos:** move the same file (and its scripts) into its own git repo and tag it — others then `agents-cli extension add <org>/<repo>#<name> --ref v1.0.0`. The file doesn't change; ad-hoc and shared are the same format.

Schema by example (`agents-cli-extension/v1alpha1`)

Everything below is optional except `run` on a command (a non-empty list). Unknown keys are rejected, so a typo fails loudly instead of silently doing nothing.

Machine-readable equivalent: `schemas/agents-cli-extension-v1alpha1.schema.json` in the agents-cli repo, generated from the same models the loader uses. Point a `yaml-language-server` modeline at it for editor validation.

# yaml-language-server: $schema=https://raw.githubusercontent.com/google/agents-cli/main/schemas/agents-cli-extension-v1alpha1.schema.json
schema: agents-cli-extension/v1alpha1
name: my-extension
description: What this extension does.
requires:
  agents_cli: ">=1.3,<2"   # example - derive from `agents-cli --version`, see below
  on_incompatible: warn    # warn (install + warn) | error (refuse at add/update, block its commands if the CLI drifts out)

commands:
  override:               # replace a built-in; user argv passes through verbatim
    deploy:
      run: ["uv", "run", "scripts/custom_deploy.py"]
      description: SBOM upload, then the built-in deploy.
    eval.generate:        # dotted name = a subcommand (group.sub)
      run: ["uv", "run", "scripts/eval_generate.py"]
      description: Framework-specific inference runner.
  add:                    # a brand-new command that doesn't exist yet
    compliance-report:
      run: ["python", "scripts/compliance_report.py"]
      description: Generate the quarterly compliance report.

Rules that matter

• **`run:` is a command vector** executed with **no shell**; user argv is appended verbatim. Paths relative to the extension dir resolve to absolute, and `$AGENTS_CLI_EXTENSION_DIR` locates sibling scripts/templates.
• **You can't override a command *group*** (e.g. `eval`) — override a specific subcommand (`eval.generate`); peers like `eval grade`/`eval compare` keep their built-in behavior.
• **Re-invoke the built-in safely.** An override runs with `AGENTS_CLI_DISABLE_OVERRIDES=1`, so calling `agents-cli deploy` inside your wrapper hits the built-in (no infinite recursion).
• **Chaining is done in a wrapper script**, since `run:` is a single vector (not a shell line). To do "check, then the built-in", point `run:` at a script that sequences the steps:

  #!/usr/bin/env bash
  set -e
  "$AGENTS_CLI_EXTENSION_DIR/scripts/compliance_check.sh"   # non-zero here aborts
  agents-cli deploy "$@"                                  # hits the built-in (guard is set)

• **Start `run:` with a program, not a script.** The vector is executed directly — no shell — so

`["python", "scripts/x.py"]` or `["uv", "run", "python", "scripts/x.py"]` works everywhere, while a bare `["scripts/x.py"]` relies on a shebang and never runs on Windows (the CLI warns if you do it). Paths in the vector are resolved relative to the extension directory, so they work from any cwd.

• **Conflicts** (same scope, shown in `agents-cli extension list` / `agents-cli info`): two extensions claiming one command is first-wins, later ignored. Cross-scope is fine — project wins over user (`--global`).
• **Declare a compatibility range** with `requires`, always. Run `agents-cli --version`, set the lower bound to that `major.minor` and the upper bound to the next major (`>=1.3,<2` if the CLI reports 1.3.x — the number in the example above is only an example). Let the user pick `on_incompatible`; default `warn`.
• `warn`: installs, runs, and warns when out of range.
• `error`: `extension add`/`update` refuse an out-of-range install, and if a later CLI upgrade moves you out of range the extension's **commands fail** with the range and the fix rather than silently running the built-in, which would do something else. The recovery commands (`install`, `extension *`) keep working either way.
• `schema` (`agents-cli-extension/v1alpha1`) tracks the manifest format, not the CLI version, and is accepted across CLI majors.

---

Adopt an existing extension

agents-cli extension add <ref> [--global] [--ref <branch|tag|sha>] [--yes]
agents-cli extension list                 # what's active, its scope, and its commands
agents-cli extension update [<name>]      # advance the pin (re-resolve the tracked ref)
agents-cli extension remove <name>        # drop it and delete its vendored copy
agents-cli info                        # shows active extensions + sources + conflicts

Reference forms

| Form | Meaning | |------|---------| | `acme/acli-extensions` | any `org/repo` on github.com | | `acme/acli-extensions#soc2-deploy` | select one extension from a multi-extension repo | | `https://git.example.com/acme/acli-extensions` | any git host — `https://`, `http://` or `ssh://` | | `git@git.example.com:acme/acli-extensions` | the same host, in scp form | | `local@../my-extension` | a local path (for development) | | `<nam