[authoring-antigravity-skills] step 6 - multiple issues, extremely poor tutorial experience

[FloGua]

The day 3 tutorial on the Developer Toolkit is extremely hard to follow from a standard Windows 11 environment. Please find here a list of the issues and steps I took to resolve. I can create separate issues if needed for better resolution tracking.

---

Environment: Windows 11 (native, then WSL 2), PowerShell/bash, uv package manager, personal machine, google-agents-cli v0.5.0.

1. PATH not updated after uvx google-agents-cli setup

• Ran uvx google-agents-cli setup. Output reported success (CLI: agents-cli installed, Scope: global), but agents-cli was not recognized in any terminal, not even after closing and reopening PowerShell.
• uv tool list confirmed google-agents-cli was installed with entry points agents-cli and google-agents-cli.
• uv tool dir showed the tool environment at %APPDATA%\uv\tools, but the actual shim .exe lived in %APPDATA%\uv\tools\google-agents-cli\Scripts\agents-cli.exe, not on PATH.
• uv's intended shim directory was C:\Users\<user>\.local\bin, which did contain the correct agents-cli.exe and google-agents-cli.exe, and was correctly present in the registry-level User PATH ([Environment]::GetEnvironmentVariable("Path", "User")).
• Despite this, $env:PATH in the live shell did not include .local\bin, even in a freshly opened, non-elevated PowerShell window, and even after running uv tool update-shell (which reported "Executable directory ... is already in PATH").
• Root cause/fix found by trial and error: the working terminal session simply needed to be opened after all the above steps had fully completed; a stale terminal opened earlier in the process never picked up the change even after multiple "fresh" reopens. Suggest documenting that uv tool update-shell + a guaranteed-fresh terminal (not just "looks new") is required, since this cost significant troubleshooting time.

2. agents-cli run fails on native Windows with no clear explanation

• After PATH was resolved, agents-cli create weather-assistant --prototype --yes, cd weather-assistant, and agents-cli install all completed successfully on native Windows.
• Ran agents-cli run "How are you?" and got:

  Error: Local server did not start within 30s.
    Check logs: .google-agents-cli/run_server.log
  

  with the referenced log file completely empty — no actionable information to debug from.

3. agents-cli playground surfaces a more verbose error revealing the real problem

• Running agents-cli playground instead produced a clearer (though still cryptic) failure:

  Running command: uv run adk web . --host 127.0.0.1 --port 8080 --allow_origins '*' --reload_agents
  Error: Got unexpected extra arguments (app Dockerfile GEMINI.md pyproject.toml README.md tests uv.lock)
  Error: Failed to start playground (exit code 2)
  

  i.e., the literal project-root file listing was being parsed as extra positional arguments to adk web.
• This appears to be a Windows-native argument-passing bug between agents-cli/uv run and the underlying adk web command. Docs do state native Windows is unsupported (WSL 2 only), but this isn't surfaced anywhere by the CLI itself — agents-cli run just times out silently with an empty log, and the user has to stumble onto playground's more verbose output to learn the real cause.
• Fix: switched to WSL 2 entirely; problem did not reproduce there.

4. Scaffolded app/agent.py template hardcodes Vertex AI auth, even when using a plain Gemini API key

• After moving to WSL 2, reinstalling the toolchain, and rerunning agents-cli create/install/run from scratch, got:

  google.auth.exceptions.DefaultCredentialsError: Fail to load 'app' module. Your default credentials were not found.
  

• Root cause: the --prototype scaffold's generated app/agent.py contains, unconditionally at import time:

  import google.auth
  _, project_id = google.auth.default()
  os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
  os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
  os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

  This forces Vertex AI auth via ADC regardless of whether the user has set GEMINI_API_KEY and intends to use the direct Gemini API path. Setting GOOGLE_GENAI_USE_VERTEXAI=FALSE as an env var beforehand has no effect, since the script overwrites it on import.
• Fix: manually removed those four lines and replaced with os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "False".
• Suggest: the --prototype template should conditionally check for GEMINI_API_KEY before defaulting to Vertex/ADC, or at minimum the docs/error message should call out this template behavior explicitly, since the docs present the Gemini-API-key path as the "no Google Cloud project required" option.

5. agents-cli run silently swallows backend errors, shows blank response instead of failing visibly

• After the auth fix, rerunning agents-cli run "How are you?" completed without throwing any terminal error, server started and stopped cleanly, but the output showed no actual response text:

  [root_agent]:
  Session: f3b142c1-7956-4f5d-a61a-fe4f2d69f2a3
    Resume with: agents-cli run "<message>" --session-id f3b142c1-7956-4f5d-a61a-fe4f2d69f2a3
  Local server stopped.
  

• The CLI gave no indication anything had gone wrong. Manually inspecting .google-agents-cli/run_server.log revealed the actual cause: a 429 RESOURCE_EXHAUSTED error from the Gemini API (AI Studio prepayment credits depleted). Without manually reading the log, this looked like an unrelated, unexplained empty-response bug rather than a billing failure.
• Suggest: agents-cli run should propagate/print backend errors (HTTP error codes, exception messages) to the terminal instead of silently rendering a blank agent response.

6. AI Studio billing/free-tier confusion (documented Google behavior, not a CLI bug, but a rough tutorial edge)

• Discovered that enabling billing on a Gemini API project removes free-tier access entirely (not additive) — once billing is on, all usage becomes billable from the first token, with no fallback to free quota.
• Attempted to use the Google Cloud "$300 free credit for new customers" trial to cover this, but it appears this credit may not apply to accounts that already have a pre-existing Cloud Billing account — there's no clear guidance in the tutorial for recovering from a depleted-credits state, despite this being a very likely outcome for anyone following the walkthrough with a non-fresh Google account.
• This isn't an agents-cli bug per se, but it's a significant rough edge worth a callout in the getting-started docs, since the tutorial doesn't warn users this could happen or how to resolve it cleanly.