google-agents-cli 1.9.0__tar.gz → 1.11.0__tar.gz

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.9.0
+Version: 1.11.0
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -13,7 +13,7 @@ Requires-Dist: click>=8.1.8,<9
 Requires-Dist: PyYAML>=6.0.2,<7
 Requires-Dist: cookiecutter>=2.6.0,<3
 Requires-Dist: jinja2>=3.1.0
-Requires-Dist: google-cloud-aiplatform[evaluation]>=1.165.0,<2
+Requires-Dist: google-cloud-aiplatform[evaluation]>=2.2.0,<3
 Requires-Dist: google-cloud-resource-manager>=1.12.0
 Requires-Dist: google-auth[pyopenssl]>=2.47.0
 Requires-Dist: pyopenssl<26.2
@@ -42,7 +42,7 @@ Provides-Extra: lint
 <div align="center">
   <img src="https://raw.githubusercontent.com/google/agents-cli/main/docs/src/assets/logo_sm.png" alt="agents-cli logo" width="120" />
   <h1><code>agents-cli</code></h1>
-  <p>The CLI and skills for building agents on Gemini Enterprise Agent Platform.</p>
+  <p>The CLI and skills for building agents on Gemini platform.</p>
 
   <p>
     <a href="#get-started">Get Started</a> &nbsp;&nbsp;|&nbsp;&nbsp;
@@ -60,7 +60,7 @@ Provides-Extra: lint
 
 Turn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.
 
-**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
+**Agents CLI in Gemini platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
 [Antigravity CLI](https://antigravity.google/) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; *and any other coding agent.*
@@ -106,8 +106,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `google-agents-cli-adk-code` | ADK Python API — agents, tools, orchestration, callbacks, state |
 | `google-agents-cli-scaffold` | Project scaffolding — `create`, `enhance`, `upgrade` |
 | `google-agents-cli-eval` | Evaluation methodology — metrics, datasets, LLM-as-judge, adaptive rubrics |
-| `google-agents-cli-deploy` | Deployment — [Agent Runtime](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
-| `google-agents-cli-publish` | Gemini Enterprise registration |
+| `google-agents-cli-deploy` | Deployment — [Agent Runtime in Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
+| `google-agents-cli-publish` | Gemini registration |
 | `google-agents-cli-observability` | Observability — Cloud Trace, logging, third-party integrations |
 
 ---
@@ -117,10 +117,10 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | Command | What it does |
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk` template, `agent_runtime` target) |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 
 <details>
 <summary>See all commands</summary>
@@ -130,7 +130,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli login` | Authenticate with Google Cloud or AI Studio |
 | `agents-cli login --status` | Show authentication status |
 | **Scaffold** | |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk` template, `agent_runtime` target) |
 | `agents-cli scaffold enhance` | Add deployment or CI/CD to an existing project |
 | `agents-cli scaffold upgrade` | Upgrade project to a newer agents-cli version |
 | **Develop** | |
@@ -148,7 +148,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli eval optimize` | Auto-tune agent prompts using eval data |
 | **Deploy & Publish** | |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 | `agents-cli infra single-project` | Provision single-project infrastructure |
 | `agents-cli infra cicd` | Set up CI/CD pipeline + staging/prod infrastructure |
 | **Other** | |

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/google/agents-cli/main/docs/src/assets/logo_sm.png" alt="agents-cli logo" width="120" />
   <h1><code>agents-cli</code></h1>
-  <p>The CLI and skills for building agents on Gemini Enterprise Agent Platform.</p>
+  <p>The CLI and skills for building agents on Gemini platform.</p>
 
   <p>
     <a href="#get-started">Get Started</a> &nbsp;&nbsp;|&nbsp;&nbsp;
@@ -19,7 +19,7 @@
 
 Turn your favorite coding assistant into an expert at building and deploying agents on Google Cloud.
 
-**Agents CLI in Agent Platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
+**Agents CLI in Gemini platform** (`agents-cli`) gives your coding agent the skills and commands to build, scale, govern, and optimize enterprise-grade agents — so you don't have to learn every CLI and service yourself.
 
 **Works seamlessly with:**
 [Antigravity CLI](https://antigravity.google/) &nbsp;•&nbsp; [Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;•&nbsp; [Codex](https://github.com/openai/codex) &nbsp;•&nbsp; *and any other coding agent.*
@@ -65,8 +65,8 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `google-agents-cli-adk-code` | ADK Python API — agents, tools, orchestration, callbacks, state |
 | `google-agents-cli-scaffold` | Project scaffolding — `create`, `enhance`, `upgrade` |
 | `google-agents-cli-eval` | Evaluation methodology — metrics, datasets, LLM-as-judge, adaptive rubrics |
-| `google-agents-cli-deploy` | Deployment — [Agent Runtime](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
-| `google-agents-cli-publish` | Gemini Enterprise registration |
+| `google-agents-cli-deploy` | Deployment — [Agent Runtime in Gemini platform](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale), [Cloud Run](https://cloud.google.com/run), [GKE](https://cloud.google.com/kubernetes-engine), CI/CD, secrets |
+| `google-agents-cli-publish` | Gemini registration |
 | `google-agents-cli-observability` | Observability — Cloud Trace, logging, third-party integrations |
 
 ---
@@ -76,10 +76,10 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | Command | What it does |
 |---------|-------------|
 | `agents-cli setup` | Install CLI + skills to coding agents |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk` template, `agent_runtime` target) |
 | `agents-cli eval run` | Run the agent over the eval dataset and grade the traces |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 
 <details>
 <summary>See all commands</summary>
@@ -89,7 +89,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli login` | Authenticate with Google Cloud or AI Studio |
 | `agents-cli login --status` | Show authentication status |
 | **Scaffold** | |
-| `agents-cli create <name>` | Create a new agent project |
+| `agents-cli create <name> -y` | Create a new agent project with defaults (`adk` template, `agent_runtime` target) |
 | `agents-cli scaffold enhance` | Add deployment or CI/CD to an existing project |
 | `agents-cli scaffold upgrade` | Upgrade project to a newer agents-cli version |
 | **Develop** | |
@@ -107,7 +107,7 @@ See the [full tutorial](https://google.github.io/agents-cli/guide/quickstart-tut
 | `agents-cli eval optimize` | Auto-tune agent prompts using eval data |
 | **Deploy & Publish** | |
 | `agents-cli deploy` | Deploy to Google Cloud |
-| `agents-cli publish gemini-enterprise` | Register with Gemini Enterprise |
+| `agents-cli publish gemini` | Register with Gemini |
 | `agents-cli infra single-project` | Provision single-project infrastructure |
 | `agents-cli infra cicd` | Set up CI/CD pipeline + staging/prod infrastructure |
 | **Other** | |

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.9.0"
+version = "1.11.0"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -16,7 +16,7 @@ dependencies = [
   "PyYAML>=6.0.2,<7",
   "cookiecutter>=2.6.0,<3",
   "jinja2>=3.1.0",
-  "google-cloud-aiplatform[evaluation]>=1.165.0,<2",
+  "google-cloud-aiplatform[evaluation]>=2.2.0,<3",
   "google-cloud-resource-manager>=1.12.0",
   "google-auth[pyopenssl]>=2.47.0",
   # pyOpenSSL 26.2 forbids mutating a used SSL Context; urllib3 does it per
@@ -135,11 +135,14 @@ ignore = ["E501", "C901", "RUF001", "UP036", "RUF067", "RUF069"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["PLR0917"]
+# The only module allowed to import private Agent Platform SDK modules; keep in
+# sync with ALLOWED_PRIVATE_IMPORT_FILES in tools/ci/check_private_imports.py.
+"src/google/agents/cli/_sdk_compat.py" = ["TID251"]
 
 [tool.ruff.lint.flake8-tidy-imports.banned-api]
 "rich.console.Console" = { msg = "Use `google.agents.cli._output.Console` instead to ensure project-wide defaults (soft_wrap=True) are applied." }
 "agentplatform.Client" = { msg = "Use `google.agents.cli._agent_platform.AgentPlatformClient` instead, so the client retries throttled requests." }
-"agentplatform._genai" = { msg = "Private SDK module that can change without notice. Use `types` from `google.agents.cli._agent_platform_types` for SDK types." }
+"agentplatform._genai" = { msg = "Private SDK module that can change without notice. Use `types` from `google.agents.cli._agent_platform_types` for SDK types, and add any other private SDK use to `google.agents.cli._sdk_compat`." }
 
 [tool.ruff.lint.pylint]
 max-positional-args = 5

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/src/google/agents/cli/_agent_platform.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Shared construction of the Agent Platform SDK client."""
+"""Shared construction of the Gemini platform SDK client."""
 
 from __future__ import annotations
 
@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
     import agentplatform
 
-# Retry options applied to every Agent Platform client the CLI builds. Leaving
+# Retry options applied to every Gemini platform client the CLI builds. Leaving
 # http_status_codes unset keeps the SDK's default retryable set (408/429/500/502/503/504);
 # waits are roughly 1s, 2s, 4s, 8s (full-jittered).
 RETRY_OPTIONS: dict[str, Any] = {
@@ -31,7 +31,7 @@ RETRY_OPTIONS: dict[str, Any] = {
 
 
 class AgentPlatformClient:
-    """Agent Platform client configured with CLI-wide defaults (e.g. retries on transient errors).
+    """Gemini platform client configured with CLI-wide defaults (e.g. retries on transient errors).
 
     Retries are opt-in in the underlying SDK, so constructing ``agentplatform.Client``
     directly runs without them. A ruff rule enforces using this wrapper instead.

google_agents_cli-1.11.0/src/google/agents/cli/_agent_platform_types.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Gemini platform SDK types.
+
+Use ``types.EvalCase``, ``types.evals.AgentEvent``, etc. from here rather than
+importing ``agentplatform._genai`` directly. ``_sdk_compat`` resolves them.
+"""
+
+from google.agents.cli._sdk_compat import types
+
+__all__ = ["types"]

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/src/google/agents/cli/_click.py

@@ -65,6 +65,7 @@ class LazyGroup(click.Group):
         # name -> experiment label
         self._experiment_gates: dict[str, str] = {}
         self._overrides: dict[str, click.Command] = {}
+        self._hidden: set[str] = set()
 
     def add_lazy_command(
         self,
@@ -72,6 +73,7 @@ class LazyGroup(click.Group):
         import_path: str,
         short_help: str,
         experiment: str | None = None,
+        hidden: bool = False,
     ) -> None:
         """Register a subcommand for lazy loading.
 
@@ -83,10 +85,20 @@ class LazyGroup(click.Group):
         not at this registration call: `main` is built once at import, so
         guarding registration would freeze visibility before a unit test could
         override the experiment.
+
+        `hidden` keeps a command invocable but out of --help and the docs, e.g.
+        an old name kept as an alias after a rename.
         """
         self._lazy_commands[name] = (import_path, short_help)
         if experiment is not None:
             self._experiment_gates[name] = experiment
+        if hidden:
+            self._hidden.add(name)
+
+    @property
+    def hidden_commands(self) -> frozenset[str]:
+        """Names registered with `hidden=True`: invocable, but not listed."""
+        return frozenset(self._hidden)
 
     def _is_visible(self, name: str) -> bool:
         """True if `name` is not hidden via experiment."""
@@ -100,7 +112,7 @@ class LazyGroup(click.Group):
             set(super().list_commands(ctx))
             | set(self._lazy_commands)
             | set(self._overrides)
-        )
+        ) - self._hidden
         return sorted(filter(self._is_visible, names))
 
     def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:

{google_agents_cli-1.9.0 → google_agents_cli-1.11.0}/src/google/agents/cli/_experiments.py

@@ -28,6 +28,10 @@ class Experiment(NamedTuple):
 _REGISTRY: dict[str, Experiment] = {
     # Hides the `build` command until Go (compiled-language) support launches.
     "build_command": Experiment("build_command", bool, True),
+    # Gate in-progress ADK language support until each language launches.
+    "adk_java": Experiment("adk_java", bool, False),
+    "adk_kotlin": Experiment("adk_kotlin", bool, False),
+    "adk_typescript": Experiment("adk_typescript", bool, False),
 }
 
 

google_agents_cli-1.11.0/src/google/agents/cli/_fs.py

@@ -0,0 +1,95 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""File system helpers for agents CLI."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import shutil
+import stat
+from pathlib import Path
+
+
+def delete_folder(folder: Path) -> None:
+    """Delete `folder`, even when it holds read-only folders; warn when it cannot."""
+    make_folders_writable(folder)
+    shutil.rmtree(folder, ignore_errors=True)
+    if folder.exists() or folder.is_symlink():
+        logging.warning("Could not delete %s; delete it by hand.", folder)
+
+
+def delete_path(path: Path) -> None:
+    """Delete `path`; unlink a link instead of following it into a folder we do not own.
+
+    Raises OSError when it cannot delete, unlike `delete_folder`, which only warns.
+    """
+    try:
+        mode = path.lstat().st_mode
+    except (FileNotFoundError, NotADirectoryError):
+        return
+    if stat.S_ISDIR(mode):
+        make_folders_writable(path)
+        shutil.rmtree(os.fspath(path))
+    else:
+        path.unlink()
+
+
+def make_folders_writable(root: Path) -> None:
+    """Let ``rmtree`` delete what read-only folders under ``root`` hold.
+
+    Best effort: a folder it cannot change is left as it is.
+    """
+    if root.is_symlink():
+        return
+    _make_writable(root)
+    for folder, subfolders, _ in os.walk(root):
+        for name in subfolders:
+            subfolder = os.path.join(folder, name)
+            # chmod follows links, so a linked folder is skipped to keep the change
+            # inside `root` (CWE-59). Each one is changed before os.walk lists it.
+            if not os.path.islink(subfolder):
+                _make_writable(subfolder)
+
+
+def _make_writable(folder: str | Path) -> None:
+    with contextlib.suppress(OSError):
+        os.chmod(folder, stat.S_IRWXU)
+
+
+def is_real_dir(path: Path) -> bool:
+    """Whether `path` is a folder and not a link: a committed link can lead anywhere.
+
+    Uses `os.path`: before Python 3.14, `Path.is_dir` and `Path.is_symlink` raise
+    PermissionError under a folder that cannot be searched.
+    """
+    return not os.path.islink(path) and os.path.isdir(path)
+
+
+def first_copy_error(error: OSError) -> str:
+    """The reason of the first failed file, instead of copytree's list of all of them."""
+    # copytree collects every failed file into one shutil.Error holding a list of
+    # (source, target, reason) tuples.
+    if isinstance(error, shutil.Error) and error.args:
+        failures = error.args[0]
+        if (
+            isinstance(failures, list)
+            and failures
+            and isinstance(failures[0], tuple)
+            and len(failures[0]) == 3
+        ):
+            return str(failures[0][2])
+    return str(error)

google_agents_cli-1.11.0/src/google/agents/cli/_git.py

@@ -0,0 +1,41 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Checks for values passed to git as arguments.
+
+A value read from a project file or typed by the user can reach git as an
+option (e.g. ``--upload-pack=<cmd>``, which runs a command). Callers check
+values with these before building a git command, and also put ``--`` before
+positional arguments where the git subcommand accepts it.
+"""
+
+import re
+
+# Only a full 40-char SHA is unambiguous. A short/partial hex string could
+# instead be a branch or tag named like hex (e.g. "cafe123").
+_COMMIT_SHA_RE = re.compile(r"[0-9a-f]{40}")
+
+
+def is_commit_sha(value: str) -> bool:
+    """True for a full 40-char lowercase hex commit SHA."""
+    # fullmatch, not match with "$": "$" also matches before a trailing newline.
+    return bool(_COMMIT_SHA_RE.fullmatch(value))
+
+
+def is_option_like(value: str) -> bool:
+    """True when git would read ``value`` as an option rather than an operand.
+
+    No valid git ref name starts with "-".
+    """
+    return value.startswith("-")

google_agents_cli-1.11.0/src/google/agents/cli/_output.py

@@ -0,0 +1,167 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Output helpers for agents CLI."""
+
+import json
+import logging
+import sys
+from typing import Any
+
+import click
+from rich.console import Console as _RichConsole  # noqa: TID251
+from rich.markup import escape
+
+_OWN_LOGGER_NAME = "google.agents.cli"
+_PLAIN_FORMATTER = logging.Formatter()
+
+
+class Console(_RichConsole):
+    """Rich Console configured with project-wide defaults (soft_wrap=True)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("soft_wrap", True)
+        super().__init__(*args, **kwargs)
+
+
+def emit(data: dict) -> None:
+    """Write structured data to stdout."""
+    print(json.dumps(data), file=sys.stdout)
+
+
+def print_error(message: str) -> None:
+    """Print an error message to stderr with a red "❌ Error:" prefix."""
+    # escape() so text like "[cyan]" or "[0]" in the message is shown as-is.
+    Console(stderr=True, highlight=False).print(
+        f"[bold red]❌ Error:[/bold red] {escape(message)}"
+    )
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message to stderr with a yellow "⚠️  Warning:" prefix."""
+    Console(stderr=True, highlight=False).print(
+        f"[bold yellow]⚠️  Warning:[/bold yellow] {escape(message)}"
+    )
+
+
+INTERACTIVE_FIX = ("-i, --interactive", "be prompted for each missing value")
+
+
+def auto_approve_fix(default: str) -> tuple[str, str]:
+    """The -y entry for programmatic_mode_error; ``default`` names what -y picks."""
+    return ("-y, --yes", f"accept the defaults ({default})")
+
+
+def programmatic_mode_error(
+    requirement: str, *fixes: tuple[str, str]
+) -> click.UsageError:
+    """Build the error for a value a command can't fill in without prompting.
+
+    ``requirement`` is the subject, e.g. "--agent is required"; each fix is a
+    (flag, description) pair, and an empty flag continues the fix above. Every
+    fix gets its own aligned line: a trailing "pass -i for interactive mode"
+    sentence was easy to miss.
+    """
+    if not fixes:
+        return click.UsageError(f"{requirement} in programmatic mode.")
+    width = max(len(flag) for flag, _ in fixes)
+    lines = "\n".join(f"  {flag:<{width}}  {text}" for flag, text in fixes)
+    return click.UsageError(
+        f"{requirement} in programmatic mode. Rerun with one of:\n{lines}"
+    )
+
+
+def print_debug(message: str) -> None:
+    """Print a debug message to stderr as a dim "Debug: <message>" line."""
+    Console(stderr=True, highlight=False).print(f"Debug: {escape(message)}", style="dim")
+
+
+def print_click_exception(e: click.ClickException) -> None:
+    """Show a ClickException like Click does, but with a red "❌ Error:" prefix."""
+    if isinstance(e, click.UsageError) and e.ctx is not None:
+        hint = ""
+        if e.ctx.command.get_help_option(e.ctx) is not None:
+            hint = f"Try '{e.ctx.command_path} {e.ctx.help_option_names[0]}' for help.\n"
+        click.echo(f"{e.ctx.get_usage()}\n{hint}", err=True, color=e.ctx.color)
+    print_error(e.format_message())
+
+
+def configure_logging(level: int = logging.INFO) -> None:
+    """Send log records to stderr, formatting agents-cli's own records.
+
+    agents-cli's own records are shown from ``level`` up. Records from libraries
+    are shown from WARNING up (or from ``level``, if it is higher), except at
+    DEBUG, where they are shown too. agents-cli's own errors, warnings and debug
+    records get the print_error() / print_warning() / print_debug() format;
+    everything else is printed plain.
+    """
+    root = logging.getLogger()
+    for handler in [h for h in root.handlers if isinstance(h, _CliLogHandler)]:
+        root.removeHandler(handler)
+
+    debug = level <= logging.DEBUG
+    library_level = level if debug else max(level, logging.WARNING)
+    handler = _CliLogHandler()
+    handler.setFormatter(
+        logging.Formatter(logging.BASIC_FORMAT if debug else "%(message)s")
+    )
+    handler.addFilter(lambda r: _is_own_record(r) or r.levelno >= library_level)
+    root.addHandler(handler)
+    root.setLevel(level)
+    # On its first request, google-auth turns off propagation on the "google"
+    # logger unless that logger is already configured
+    # (google.auth._helpers.is_logging_enabled). That would cut every google.*
+    # logger, ours included, off from the handler above. A level counts as
+    # configured. At DEBUG, google-auth then logs its requests; their headers
+    # (with tokens) go in the record's extra fields, which this format doesn't
+    # print.
+    logging.getLogger("google").setLevel(level)
+
+
+class _CliLogHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            printer = _OWN_RECORD_PRINTERS.get(record.levelno)
+            if printer and _is_own_record(record):
+                printer(_PLAIN_FORMATTER.format(record))
+            else:
+                # click.echo looks up sys.stderr on every call, so output still
+                # reaches a stream swapped in later (e.g. by CliRunner).
+                click.echo(self.format(record), err=True)
+        except Exception:
+            self.handleError(record)
+
+
+def _is_own_record(record: logging.LogRecord) -> bool:
+    # agents-cli code mostly calls logging.warning() etc. directly, which logs
+    # on the root logger.
+    return (
+        record.name == "root"
+        or record.name == _OWN_LOGGER_NAME
+        or record.name.startswith(_OWN_LOGGER_NAME + ".")
+    )
+
+
+def _print_plain(message: str) -> None:
+    # Our INFO lines stay plain, without the debug-mode "INFO:root:" prefix.
+    click.echo(message, err=True)
+
+
+_OWN_RECORD_PRINTERS = {
+    logging.CRITICAL: print_error,
+    logging.ERROR: print_error,
+    logging.WARNING: print_warning,
+    logging.INFO: _print_plain,
+    logging.DEBUG: print_debug,
+}