FileNotFoundError in setup when gcloud is missing (Contradicts README/FAQ)

[jarrodcolburn]

Description

The google-agents-cli setup command crashes with a FileNotFoundError if the Google Cloud SDK (gcloud) is not installed. This creates a significant "first-mile" failure for new users, especially those following the "Local Development" path described in the documentation.

Documentation Inconsistencies & User Frustration

The current behavior directly contradicts the project's documentation, leading to a confusing setup experience:

• README Prerequisites: The README lists only Python 3.11+, uv, and Node.js as prerequisites. gcloud is not mentioned as a requirement for installation or basic setup.

• FAQ Contradiction: The FAQ explicitly states:

  "Do I need Google Cloud? For local development (create, run, eval), no — you can use an AI Studio API key to run Gemini with ADK locally."

  Despite this, setup crashes immediately upon checking for Google Cloud credentials, preventing users from ever reaching the point where they could configure an AI Studio API key.

• Brittle Authentication Check: Even when running setup non-interactively, the CLI attempts to verify the environment's authentication status. Instead of gracefully failing or falling back to API key detection, it assumes the presence of the gcloud binary.

Steps to Reproduce

1. Use an environment (Linux/macOS) where gcloud is not in the PATH.
2. Run the recommended install command: uvx google-agents-cli setup.

Actual Behavior

The CLI crashes during the authentication check phase:

Traceback (most recent call last):
  ...
  File ".../google/agents/cli/auth.py", line 366, in is_authenticated
    if not _check_valid_adc():
  File ".../google/agents/cli/auth.py", line 382, in _check_valid_adc
    subprocess.run(
        ["gcloud", "auth", "application-default", "print-access-token", "--quiet"],
        check=True,
        capture_output=True,
    )
  ...
FileNotFoundError: [Errno 2] No such file or directory: 'gcloud'

Technical Root Cause

In google/agents/cli/auth.py, the _check_valid_adc function only catches subprocess.CalledProcessError. It should also catch FileNotFoundError to handle cases where the Google Cloud SDK is not installed.

# Proposed fix in google/agents/cli/auth.py
def _check_valid_adc():
    try:
        subprocess.run(["gcloud", ...], check=True, capture_output=True)
        return True
    except (subprocess.CalledProcessError, FileNotFoundError): 
        return False

Workaround for Users

Currently, users must use the undocumented --skip-auth flag to bypass the crash:
uvx google-agents-cli setup --skip-auth

[sushicw]

Thank you for the report!

This should be improved in the upcoming 0.2.0 release:

crwilson@crwilson:~/tmp$ uvx google-agents-cli setup
Setting up...

 █▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀   █▀▀ █  █
 █▀█ █▄█ ██▄ █ ▀█  █  ▄█   █▄▄ █▄ █

 Give your coding agent the power to build ADK projects.

 1. Authentication
 ─────────────────
agents-cli v0.2.0
Error: 'gcloud' is not installed or not on PATH.
  Install the Google Cloud SDK (https://cloud.google.com/sdk/docs/install) and ensure it is in your PATH.

[sushicw]

agents-cli 0.2.0 just released.

But the issue remains that our docs are not totally consistent on what is required, and that needs to be resolved still, so keeping this open for now.