C3 exit codes + --agent-mode, 2026-10-30 08:53:46-08:53:47 (UTC+8). env -i, empty HOME, normal network (these calls are meant to reach Google).

Summary (command -> expected / observed exit, stderr):
 models --agent-mode (offline catalog)                 0 / 0   stdout TOON list, 34 models
 generate hi --no-such-flag --agent-mode               2 / 2   JSON envelope validation_error
 generate hi --no-such-flag (no agent mode)            2 / 2   human-readable 'Error (validation_error)'
 generate hi, no key at all (GEMINI_NO_KEYRING=1)      3 / 3   JSON authentication_error; NOTE the CLI still sent the request and Google answered 403 'unregistered callers' (no local 'no key' check)
 generate hi, fake key                                 3 / 3   JSON authentication_error, API_KEY_INVALID (HTTP 400)
 generate hi, fake key, no agent mode                  3 / 3   human-readable error + fix hints
 models list, fake key                                 3 / 3   JSON authentication_error
 generate hi --server-url http://127.0.0.1:1           1 / 1   JSON connection_error (connection refused)
 models get no-such-model-xyz, fake key                (we expected 1) / 3 — our test design error: the fake key fails auth before the model lookup, so 3 is correct; not counted.
All four documented codes (0,1,2,3) observed on the matching cause; every --agent-mode error was a single JSON object on stderr with error, error_reason, error_type, exit_code, hints. Fake key string appeared 0 times in output. Each call 0.03-0.19 s.

Raw stderr:
== ok

== badflag
{
  "error": "unknown flag: --no-such-flag",
  "error_reason": "CLI_VALIDATION",
  "error_type": "validation_error",
  "exit_code": 2,
  "hints": [
    "Run 'gemini-api generate --help' for usage and examples, or --usage for the machine-readable surface"
  ],
  "message": "unknown flag: --no-such-flag"
}

== badflag-plain
Error (validation_error): unknown flag: --no-such-flag
Reason: CLI_VALIDATION
Fix:
  - Run 'gemini-api generate --help' for usage and examples, or --usage for the machine-readable surface

== nokey
{
  "error": {
    "code": 403,
    "message": "Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.",
    "status": "PERMISSION_DENIED"
  },
  "error_reason": "PERMISSION_DENIED",
  "error_type": "authentication_error",
  "exit_code": 3,
  "hints": [
    "Set GEMINI_API_KEY to a valid key (see https://ai.google.dev/gemini-api/docs/api-key), pass a valid --access-token, or run \"gemini-api configure\" to store one",
    "Run \"gemini-api whoami\" to see which credential is being sent",
    "AI agents: API keys must be created manually by the user in Google AI Studio; access tokens come from the user's own Google sign-in. Stop and ask the user to run \"gemini-api configure\" or set a valid GEMINI_API_KEY; do not run configure yourself or retry until they confirm it is set"
  ],
  "mess
== fakekey
{
  "error": {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        },
        "reason": "API_KEY_INVALID"
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ],
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT"
  },
  "error_reason": "API_KEY_INVALID",
  "error_type": "authentication_error",
  "exit_code": 3,
  "hints": [
    "The API key was rejected. See https://ai.google.dev/gemini-api/docs/api-key for how to create a new one, then export GEMINI_API_KEY=API_KEY (or run \"gemini-api configure\" to store it)",
    "Run \"gemini-a
== fakekey-plain
Error (authentication_error): API key not valid. Please pass a valid API key.
Reason: API_KEY_INVALID (HTTP 400)
Fix:
  - The API key was rejected. See https://ai.google.dev/gemini-api/docs/api-key for how to create a new one, then export GEMINI_API_KEY=API_KEY (or run "gemini-api configure" to store it)
  - Run "gemini-api whoami" to see which credential is being sent
  - AI agents: a replacement API key must be created manually by the user in Google AI Studio. Stop and ask the user to run "gemini-api configure" or set GEMINI_API_KEY to a valid key; do not run configure yourself or retry until they confirm it is set
Details:
  {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": 
== fakekey-models
{
  "error": {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        },
        "reason": "API_KEY_INVALID"
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ],
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT"
  },
  "error_reason": "API_KEY_INVALID",
  "error_type": "authentication_error",
  "exit_code": 3,
  "hints": [
    "The API key was rejected. See https://ai.google.dev/gemini-api/docs/api-key for how to create a new one, then export GEMINI_API_KEY=API_KEY (or run \"gemini-api configure\" to store it)",
    "Run \"gemini-a
== runtime
{
  "error": "error sending request: Post \"http://127.0.0.1:1/v1beta/interactions\": dial tcp 127.0.0.1:1: connect: connection refused",
  "error_reason": "CLI_CONNECTION",
  "error_type": "connection_error",
  "exit_code": 1,
  "hints": [
    "Check network connectivity",
    "Verify the server URL with --server-url"
  ],
  "message": "error sending request: Post \"http://127.0.0.1:1/v1beta/interactions\": dial tcp 127.0.0.1:1: connect: connection refused"
}

== notfound
{
  "error": {
    "code": 400,
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        },
        "reason": "API_KEY_INVALID"
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ],
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT"
  },
  "error_reason": "API_KEY_INVALID",
  "error_type": "authentication_error",
  "exit_code": 3,
  "hints": [
    "The API key was rejected. See https://ai.google.dev/gemini-api/docs/api-key for how to create a new one, then export GEMINI_API_KEY=API_KEY (or run \"gemini-api configure\" to store it)",
    "Run \"gemini-a