name "gemini-api"
bin "gemini-api"
about """
  Gemini API: Use the Gemini Interactions API and managed-agent platform from the command line.

  Get started:
    Set GEMINI_API_KEY, or run: gemini-api configure
    Then run a model or managed agent: gemini-api agent --help
    Add --dry-run to preview any API call without sending it.
  """
version "0.4.4"
config {
  file "~/.config/gemini-api/config.yaml"
}
flag "--usage" help="Print the CLI Usage schema in KDL format" global=#true
flag "--help-global" help="Print global flags shared by every command"
flag "-v --version" help="Print the CLI version"
flag "-o --output-format <format>" help="Specify the output format. Options: pretty, json, yaml, table, toon." global=#true config="output_format" default="pretty"
flag "--color <color>" help="Control colored output: auto (color when output is a TTY), always, or never. Respects NO_COLOR and FORCE_COLOR env vars." global=#true default="auto"
flag "-q --jq <jq>" help="Filter and transform output using a jq expression (e.g., '.name', '.items[] | .id')" global=#true
flag "--raw-output" help="Write --jq string results as raw text instead of JSON strings (like jq -r); non-string results stay JSON" global=#true default=#true
flag "--server-url <url>" help="Override the default server URL" global=#true
flag "-H --header <header...>" help="Set a custom HTTP request header (format: \"Key: Value\"). Can be specified multiple times." global=#true var=#true
flag "--include-headers" help="Include HTTP response headers in the output" global=#true default=#false
flag "--timeout <duration>" help="HTTP request timeout (e.g., 30s, 5m, 100ms)" global=#true config="timeout"
flag "--interactive" help="Prompt for missing inputs and open guided configure/auth forms (forms fall back to line prompts on stdin off-TTY)" global=#true default=#false
flag "--no-interactive" help="Disable all interactive features (auto-prompting, explorer auto-launch, TUI forms)" global=#true default=#false
flag "--dry-run" help="Preview API requests without sending them (no network, no OS keychain). Human preview on stderr; with -o json or --jq, one JSON object per request on stdout. Local mutation commands (auth login, auth logout and configure) make no request: they skip prompts and writes and report a no-op (stderr, or one JSON object on stdout in the machine form)" global=#true default=#false
flag "-d --debug" help="Log request and response diagnostics to stderr" global=#true default=#false
flag "--agent-mode" help="Enable structured errors and default TOON output for AI coding agents." global=#true default=#false
flag "--no-retries" help="Disable automatic retries (default: retries enabled with exponential backoff)" global=#true config="no_retries" default=#false hide=#true
flag "--retry-max-elapsed-time <duration>" help="Maximum total time for retries (e.g., 30s, 5m). Default: 30s" global=#true config="retry_max_elapsed_time" hide=#true
flag "--retry-connection-errors" help="Retry on connection errors (EOF, reset, etc.)" global=#true config="retry_connection_errors" default=#false hide=#true
flag "--retry-config <json>" help="Full retry config as JSON. Schema: {\"strategy\":\"backoff\",\"backoff\":{\"initialInterval\":500,\"maxInterval\":10000,\"exponent\":1.5,\"maxElapsedTime\":30000},\"retryConnectionErrors\":false}. Use strategy \"attempt-count-backoff\" with maxRetries for attempt-count retries. Times are in milliseconds." global=#true config="retry_config" hide=#true
flag "--api-key <api_key>" help="Gemini API key sent as x-goog-api-key." global=#true env="GEMINI_API_KEY" config="security.api_key"
flag "--access-token <access_token>" help="OAuth access token sent as a bearer Authorization header." global=#true env="GEMINI_ACCESS_TOKEN" config="security.access_token"
flag "--no-keyring" help="Never read or write the OS keychain; store secrets in the config file instead" global=#true env="GEMINI_NO_KEYRING" config="no_keyring" default=#false
flag "--api-version <api_version>" help="Which version of the API to use" global=#true env="GEMINI_API_VERSION" config="globals.api_version" default="v1beta"
flag "--api-revision <api_revision>" help="Interactions API revision to request" global=#true env="GEMINI_API_REVISION" config="globals.api_revision"
flag "--user-project <user_project>" help="Quota project header to send with Google GenAI API requests" global=#true env="GEMINI_USER_PROJECT" config="globals.user_project"
cmd "agent" help="Run interactions with Gemini models or managed agents, and manage agent definitions" {
  cmd "run" help="Run an interaction with a Gemini model or a managed agent" {
    arg "input" help="Prompt or task to send" required=#true var=#true
    flag "--body <body>" help="Request body as JSON (advanced; merges with intent inputs, rejecting duplicate keys). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
    flag "--agent <agent>" help="Managed agent to run (see \"gemini-api agent list\") (e.g. deep-research-pro-preview-12-2025, deep-research-preview-04-2026, deep-research-max-preview-04-2026, antigravity-preview-05-2026)" {
      suggestions "deep-research-pro-preview-12-2025" "deep-research-preview-04-2026" "deep-research-max-preview-04-2026" "antigravity-preview-05-2026"
    }
    flag "--background" help="Return immediately with an interaction ID; poll with \"gemini-api agent status\""
    flag "-m --model <model>" help="Model to run (see \"gemini-api models\") (e.g. gemma-4-26b-a4b-it, gemma-4-31b-it, gemini-flash-latest, gemini-flash-lite-latest, ..., default: gemini-3.8-flash)" default="gemini-3.8-flash" {
      suggestions "gemma-4-26b-a4b-it" "gemma-4-31b-it" "gemini-flash-latest" "gemini-flash-lite-latest" "gemini-pro-latest" "gemini-2.5-flash" "gemini-2.5-pro" "gemini-2.5-flash-lite" "gemini-3.5-flash-lite" "gemini-2.5-flash-image" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "gemini-3.1-pro-preview-customtools" "gemini-3.1-flash-lite" "gemini-3.1-flash-lite-image" "gemini-3-pro-image" "nano-banana-pro-preview" "gemini-3.1-flash-image" "gemini-nano-banana-2.1" "gemini-3.1-flash-tts-preview" "gemini-3.5-flash" "gemini-3.6-flash" "gemini-3.7-flash" "gemini-3.8-flash" "gemini-4-argon" "gemini-3.8-flash-tts" "gemini-3.8-flash-lite-tts" "lyria-3-clip-preview" "lyria-3-pro-preview" "gemini-robotics-er-1.6-preview" "gemini-robotics-er-2-preview" "lyria-3.5" "gemini-omni-1.1-flash" "gemini-omni-flash-preview"
    }
    flag "--previous-interaction-id <previous_interaction_id>" help="Continue from an earlier interaction by passing its interaction ID"
    flag "--stream" help="Stream the reply as it is generated; use --stream=false for one complete interaction (default: true)" default=#true
    flag "-i --input <input...>" help="Local path, files/<id>, or YouTube URL to include as input (repeatable)" var=#true
    flag "--mime-type <mime_type>" help="Override the detected MIME type (one --input only)"
  }
  cmd "cancel" help="Cancel an in-progress interaction by interaction ID" {
    arg "id" help="Required. The name of the interaction to cancel. (or use --id)"
    flag "-i --id <id>" help="Required. The name of the interaction to cancel. (or pass it as the [id] argument)"
  }
  cmd "create" help="Create a managed agent definition" {
    flag "-a --agent-config <agent_config>" help="{ \"max_total_tokens\": string, \"model\": string }"
    flag "--base-agent <base_agent>" help="The base agent to extend. [required]"
    flag "--base-environment <base_environment>" help="{ \"env\": object, \"environment_id\": string, \"network\": object | string, \"sources\": object[] } | string"
    flag "--description <description>" help="Agent description for developers to quickly read and understand."
    flag "-i --id <id>" help="The unique identifier for the agent. [required]"
    flag "-s --system-instruction <system_instruction>" help="System instruction for the agent."
    flag "-t --tools <tools>" help="The tools available to the agent. (JSON array)"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "delete" help="Delete a managed agent definition by ID" {
    arg "id" help="Required. The name of the agent to delete. (or use --id)"
    flag "-i --id <id>" help="Required. The name of the agent to delete. (or pass it as the [id] argument)"
  }
  cmd "delete-interaction" help="Delete an interaction by interaction ID" {
    alias "di"
    arg "id" help="Required. The name of the interaction to delete. (or use --id)"
    flag "-i --id <id>" help="Required. The name of the interaction to delete. (or pass it as the [id] argument)"
  }
  cmd "get" help="Get a managed agent definition by ID" {
    arg "id" help="Required. The name of the agent to retrieve. (or use --id)"
    flag "-i --id <id>" help="Required. The name of the agent to retrieve. (or pass it as the [id] argument)"
  }
  cmd "list" help="List managed agent definitions" {
    flag "--page-size <page_size>" help="Maximum number of agents to return per page"
    flag "--page-token <page_token>" help="Page token from a previous agent list call"
    flag "--parent <parent>" help="Parent resource to list agents from, as projects/<project>/locations/<location>"
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "status" help="Get status and output of an interaction by interaction ID" {
    arg "id" help="Required. The name of the interaction to retrieve. (or use --id)"
    flag "--include-input" help="If true, includes the input in the response."
    flag "-i --id <id>" help="Required. The name of the interaction to retrieve. (or pass it as the [id] argument)"
    flag "-l --last-event-id <last_event_id>" help="""
      If set, resumes the interaction stream from the chunk after the event
      marked by the event id. Can only be used if 'stream' is true.
      """
    flag "-s --stream" help="Stream the interaction's events (replayed from the start for a finished interaction) instead of returning the status object. Defaults to false; use --stream to stream events." default=#false
  }
}
cmd "analyze" help="Ask questions about images, audio, video, documents, text files, or YouTube URLs (gemini-3.8-flash)" {
  arg "question" help="Question to ask (default: \"Describe this file in detail.\")" var=#true
  flag "-i --input <input...>" help="Local path, files/<id>, or YouTube URL to analyze (repeatable)" var=#true
  flag "--mime-type <mime_type>" help="Override the detected MIME type (one input only)"
  flag "-m --model <model>" help="Override model (default: gemini-3.8-flash) — text-capable models: https://ai.google.dev/gemini-api/docs/models"
  flag "--stdin" help="Read text to analyze from stdin to EOF (sent after the --input media, before the question)"
  flag "--system <system>" help="System instruction to steer the analysis"
}
cmd "auth" help="Manage authentication credentials" {
  cmd "login" help="Interactively configure authentication credentials"
  cmd "logout" help="Clear all stored authentication credentials"
  cmd "whoami" help="Display current authentication and global parameter configuration"
}
cmd "configure" help="Configure authentication, global parameters, and preferences" {
  flag "--default-output-format <format>" help="Store the default output format without opening the form. Options: pretty, json, yaml, table, toon. Pass an empty value to clear it." {
    suggestions "pretty" "json" "yaml" "table" "toon"
  }
}
cmd "credentials" help="Manage stored credentials (bearer tokens, OAuth2, environment variables) that agents inject into outgoing HTTP requests" {
  cmd "create" help="Create a credential" {
    flag "-b --body-param <body_param>" help="{ \"id\": string, \"injection_location\": string | string[], \"value\": string, ... } | { \"id\": string, \"token\": string, ... } | { \"client_id\": string, \"client_secret\": string, \"id\": string, \"refresh_token\": string, ... }"
    flag "--body-param.environment-variable <environment_variable>" help="EnvironmentVariableConfig variant as JSON"
    flag "--body-param.bearer-token <bearer_token>" help="HttpBearerConfig variant as JSON"
    flag "--body-param.bearer-token.header-name <header_name>" help="""
      Optional. Header name to inject the token into. Defaults to
      'Authorization'.
      """
    flag "--body-param.bearer-token.id <id>" help="Required. Unique identifier for the credential. [required]"
    flag "--body-param.bearer-token.prefix <prefix>" help="""
      Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to ''
      for no prefix.
      """
    flag "--body-param.bearer-token.token <token>" help="Required. Input only. The static bearer token. Write-only; never returned in responses. [required]"
    flag "--body-param.oauth2 <oauth2>" help="OAuth2Config variant as JSON"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "delete" help="Delete a credential by ID" {
    arg "id" help="Credential ID, as given on create (or use --id)"
    flag "-i --id <id>" help="Credential ID, as given on create (or pass it as the [id] argument)"
  }
  cmd "get" help="Get a credential by ID" {
    arg "id" help="Credential ID, as given on create (or use --id)"
    flag "-i --id <id>" help="Credential ID, as given on create (or pass it as the [id] argument)"
  }
  cmd "list" help="List credentials" {
    flag "--page-size <page_size>" help="Optional. Maximum number of credentials to return."
    flag "--page-token <page_token>" help="Optional. Pagination token."
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "update" help="Update a credential by ID" {
    arg "id" help="Credential ID, as given on create (or use --id)"
    flag "-i --id <id>" help="Credential ID, as given on create (or pass it as the [id] argument)"
    flag "-u --update-mask <update_mask>" help="Optional. The list of fields to update."
    flag "-b --body-param <body_param>" help="{ \"injection_location\": string | string[], \"trusted_domains\": string[], \"value\": string } | { \"header_name\": string, \"prefix\": string, \"token\": string } | { \"client_id\": string, \"client_secret\": string, \"refresh_token\": string, \"scopes\": string[], ... }"
    flag "--body-param.environment-variable <environment_variable>" help="EnvironmentVariableUpdateConfig variant as JSON"
    flag "--body-param.bearer-token <bearer_token>" help="HttpBearerUpdateConfig variant as JSON"
    flag "--body-param.bearer-token.header-name <header_name>" help="""
      Optional. Header name to inject the token into. Defaults to
      'Authorization'.
      """
    flag "--body-param.bearer-token.prefix <prefix>" help="""
      Optional. Prefix to prepend to the token. Defaults to 'Bearer'. Set to ''
      for no prefix.
      """
    flag "--body-param.bearer-token.token <token>" help="Optional. Input only. The static bearer token. Write-only; never returned in responses."
    flag "--body-param.oauth2 <oauth2>" help="OAuth2UpdateConfig variant as JSON"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
}
cmd "environments" help="Manage sandbox environments and inspect environment files" {
  cmd "create" help="Create a sandbox environment" {
    flag "-f --from-environment <from_environment>" help="""
      Optional. The source environment to copy/fork from.
      Format: 'environments/{environment_id}' or '{environment_id}'.
      When specified, 'sources' and 'env' must be empty.
      """
    flag "-n --network <network>" help="{ \"allowlist\": object[] | string } | CreateEnvironmentRequest_network_enum"
    flag "-s --sources <sources>" help="Sources to be mounted into the environment. (JSON array)"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "delete" help="Delete a sandbox environment by ID" {
    arg "id" help="""
      Required. Resource ID segment making up resource 'name'. It identifies the resource
      within its parent collection as described in https://google.aip.dev/122. (or use --id)
      """
    flag "-i --id <id>" help="""
      Required. Resource ID segment making up resource 'name'. It identifies the resource
      within its parent collection as described in https://google.aip.dev/122. (or pass it as the [id] argument)
      """
  }
  cmd "files" help="List and inspect files in an environment's snapshot" {
    cmd "list" help="List or inspect files in an environment snapshot" {
      flag "-e --environment <environment>" help="Environment to read, as environments/<id> or a bare id [required]"
      flag "-p --path <path>" help="File or directory path relative to the workspace root, e.g. src; a leading slash is ignored [required]"
      flag "--page-size <page_size>" help="Optional. Maximum number of entries to return per page (for directory listing)."
      flag "--page-token <page_token>" help="Optional. Pagination token for directory listing."
      flag "-r --recursive" help="Optional. If true and the path is a directory, recursively lists all files."
      flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
      flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
    }
    cmd "download" help="Download a single file's raw content from an environment" {
      args "<environment> <path>"
      flag "--out <out>" help="Write the downloaded file to this path or into this directory (default: ./<basename>)"
    }
    cmd "upload" help="Upload a local file or archive into an environment" {
      args "<environment> <local-file>"
      flag "--extract" help="Extract a caller-provided .tar or .tar.gz archive into the destination directory"
      flag "--mime-type <mime_type>" help="MIME type override (inferred from file extension when omitted)"
      flag "--overwrite" help="Overwrite existing file(s) at the destination path"
      flag "-p --path <path>" help="Destination path inside the environment (default: basename of <local-file>)"
    }
  }
  cmd "get" help="Get a sandbox environment by ID" {
    arg "id" help="""
      Required. Resource ID segment making up resource 'name'. It identifies the resource
      within its parent collection as described in https://google.aip.dev/122. (or use --id)
      """
    flag "-i --id <id>" help="""
      Required. Resource ID segment making up resource 'name'. It identifies the resource
      within its parent collection as described in https://google.aip.dev/122. (or pass it as the [id] argument)
      """
  }
  cmd "list" help="List sandbox environments" {
    flag "--page-size <page_size>" help="""
      Optional. Maximum number of environments to return.
      If unspecified, defaults to 50. Maximum is 1000.
      """
    flag "--page-token <page_token>" help="Optional. Pagination token."
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
}
cmd "files" help="Upload, list, inspect, register, and delete files (48-hour retention)" {
  cmd "delete" help="Delete a file" {
    arg "file" help="File to delete, as files/<id> or a bare id (or use --file)"
    flag "-f --file <file>" help="File to delete, as files/<id> or a bare id (or pass it as the [file] argument)"
  }
  cmd "generated-files-list" help="List files generated on the project's behalf" {
    alias "gfl"
    flag "--page-size <page_size>" help="Maximum number of generated files to return per page (default 10, maximum 50)"
    flag "--page-token <page_token>" help="Page token from a previous generated-files list call"
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "get" help="Get a file's metadata and processing state" {
    arg "file" help="File to get, as files/<id> or a bare id (or use --file)"
    flag "-f --file <file>" help="File to get, as files/<id> or a bare id (or pass it as the [file] argument)"
  }
  cmd "list" help="List uploaded and registered files" {
    flag "--page-size <page_size>" help="Maximum number of files to return per page (default 10, maximum 100)"
    flag "--page-token <page_token>" help="Page token from a previous files list call"
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "register" help="Register Google Cloud Storage objects as files without copying them" {
    flag "-u --uris <uris>" help="Required. The gs:// URIs of the Google Cloud Storage objects to register. (JSON array) [required]"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "upload" help="Upload a local file to the Files API (48h TTL)" {
    arg "path" help="Local file to upload" required=#true
    flag "--display-name <display_name>" help="Human-readable display name for the file"
    flag "--mime-type <mime_type>" help="Override the detected MIME type"
    flag "--wait" help="Wait until the uploaded file is ready for use"
    flag "--wait-timeout <wait_timeout>" help="Maximum time to wait when --wait is set"
  }
}
cmd "generate" help="Text & multimodal generation (gemini-3.8-flash)" {
  arg "prompt" help="Prompt to send to the model" required=#true var=#true
  flag "--body <body>" help="Request body as JSON (advanced; merges with intent inputs, rejecting duplicate keys). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
  flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  flag "-m --model <model>" help="Model to use (see \"gemini-api models\") (e.g. gemma-4-26b-a4b-it, gemma-4-31b-it, gemini-flash-latest, gemini-flash-lite-latest, ..., default: gemini-3.8-flash)" default="gemini-3.8-flash" {
    suggestions "gemma-4-26b-a4b-it" "gemma-4-31b-it" "gemini-flash-latest" "gemini-flash-lite-latest" "gemini-pro-latest" "gemini-2.5-flash" "gemini-2.5-pro" "gemini-2.5-flash-lite" "gemini-3.5-flash-lite" "gemini-2.5-flash-image" "gemini-3-flash-preview" "gemini-3.1-pro-preview" "gemini-3.1-pro-preview-customtools" "gemini-3.1-flash-lite" "gemini-3.1-flash-lite-image" "gemini-3-pro-image" "nano-banana-pro-preview" "gemini-3.1-flash-image" "gemini-nano-banana-2.1" "gemini-3.1-flash-tts-preview" "gemini-3.5-flash" "gemini-3.6-flash" "gemini-3.7-flash" "gemini-3.8-flash" "gemini-4-argon" "gemini-3.8-flash-tts" "gemini-3.8-flash-lite-tts" "lyria-3-clip-preview" "lyria-3-pro-preview" "gemini-robotics-er-1.6-preview" "gemini-robotics-er-2-preview" "lyria-3.5" "gemini-omni-1.1-flash" "gemini-omni-flash-preview"
  }
  flag "--previous-interaction-id <previous_interaction_id>" help="Continue from an earlier interaction by passing its interaction ID"
  flag "--stream" help="Stream the reply as it is generated; use --stream=false for a single complete result (default: true)" default=#true
  flag "--system <system>" help="System instruction to steer the model"
  flag "-i --input <input...>" help="Local path, files/<id>, or YouTube URL to include as input (repeatable)" var=#true
  flag "--mime-type <mime_type>" help="Override the detected MIME type (one --input only)"
  flag "--stdin" help="Read prompt text from stdin to EOF instead of a JSON body (sent before the positional prompt, if any)"
}
cmd "image" help="Generate or edit images (gemini-nano-banana-2.1)" {
  arg "prompt" help="Image prompt" required=#true var=#true
  flag "--body <body>" help="Request body as JSON (advanced; merges with intent inputs, rejecting duplicate keys). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
  flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  flag "--aspect-ratio <aspect_ratio>" help="Aspect ratio of the output image (e.g. 1:1, 2:3, 3:2, 3:4, ...)" {
    suggestions "1:1" "2:3" "3:2" "3:4" "4:3" "4:5" "5:4" "9:16" "16:9" "21:9" "1:8" "8:1" "1:4" "4:1"
  }
  flag "--image-size <image_size>" help="Size of the output image (e.g. 512, 1K, 2K, 4K)" {
    suggestions "512" "1K" "2K" "4K"
  }
  flag "-m --model <model>" help="Override the image model (e.g. gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-3-pro-image, nano-banana-pro-preview, default: gemini-nano-banana-2.1)" default="gemini-nano-banana-2.1" {
    suggestions "gemini-nano-banana-2.1" "gemini-3.1-flash-image" "gemini-3.1-flash-lite-image" "gemini-3-pro-image" "nano-banana-pro-preview"
  }
  flag "--output-mime-type <output_mime_type>" help="MIME type of the output image (e.g. image/jpeg)" {
    suggestions "image/jpeg"
  }
  flag "--previous-interaction-id <previous_interaction_id>" help="Continue from an earlier interaction, editing the image it produced"
  flag "--out <path>" help="Write the image to this file (or into this directory). Default: ./gemini-image-{timestamp}-{rand}.{ext}"
  flag "--raw-response" help="Print the raw API response instead of writing the image to a file"
  flag "-i --input <input...>" help="Local path, files/<id>, or YouTube URL to include as input (repeatable)" var=#true
  flag "--mime-type <mime_type>" help="Override the detected MIME type (one --input only)"
  flag "--stdin" help="Read prompt text from stdin to EOF instead of a JSON body (sent before the positional prompt, if any)"
}
cmd "models" help="Show the curated offline model catalog; list/get query the live API" {
  cmd "get" help="Get a model's live metadata (version, token limits, supported methods)" {
    arg "model" help="Model id, e.g. gemini-flash-latest (or use --model)"
    flag "-m --model <model>" help="Model id, e.g. gemini-flash-latest (or pass it as the [model] argument)"
  }
  cmd "list" help="List the models the API serves (live; bare \"models\" is the offline catalog)" {
    flag "--page-size <page_size>" help="Maximum number of models to return per page (default 1000, maximum 1000)" default=1000
    flag "--page-token <page_token>" help="Page token from a previous models list call"
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
}
cmd "music" help="Music generation (lyria-3.5)" {
  arg "prompt" help="Music prompt" required=#true var=#true
  flag "--body <body>" help="Request body as JSON (advanced; merges with intent inputs, rejecting duplicate keys). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
  flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  flag "-m --model <model>" help="Override the music model (e.g. lyria-3-pro-preview, lyria-3-clip-preview, default: lyria-3.5)" default="lyria-3.5" {
    suggestions "lyria-3.5" "lyria-3-pro-preview" "lyria-3-clip-preview"
  }
  flag "--out <path>" help="Write the audio to this file (or into this directory). Default: ./gemini-music-{timestamp}-{rand}.{ext}"
  flag "--raw-response" help="Print the raw API response instead of writing the audio to a file"
  flag "-f --file <file>" help="Read prompt text from a file (sent before the positional prompt, if any)"
  flag "--stdin" help="Read prompt text from stdin to EOF instead of a JSON body (sent before the positional prompt, if any)"
}
cmd "transcribe" help="Audio/video → text (timestamps, captions) (gemini-3.8-flash)" {
  flag "--format <format>" help="Transcript format: md, text, json, srt (alias: captions)"
  flag "-i --input <input...>" help="Local path or files/<id> to transcribe (repeatable)" var=#true
  flag "--mime-type <mime_type>" help="Override the detected MIME type (one input only)"
  flag "-m --model <model>" help="Override model (default: gemini-3.8-flash) — transcription-capable models: https://ai.google.dev/gemini-api/docs/models"
  flag "--no-speakers" help="Do not label speakers"
  flag "--no-timestamps" help="Do not include timestamps (ignored for srt)"
  flag "--out <out>" help="Output path (default: ./transcript-<unix-ms>-<random>.<ext>)"
}
cmd "triggers" help="Schedule and manage cron triggers that run managed agents" {
  cmd "delete" help="Delete a trigger by ID" {
    arg "id" help="Required. Resource name of the trigger. (or use --id)"
    flag "-i --id <id>" help="Required. Resource name of the trigger. (or pass it as the [id] argument)"
  }
  cmd "get" help="Get a trigger by ID" {
    arg "id" help="Required. Resource name of the trigger. (or use --id)"
    flag "-i --id <id>" help="Required. Resource name of the trigger. (or pass it as the [id] argument)"
  }
  cmd "list" help="List triggers for a project" {
    flag "-f --filter <filter>" help="Optional. Filter expression (e.g., by state)."
    flag "--page-size <page_size>" help="Optional. The maximum number of triggers to return per page."
    flag "--page-token <page_token>" help="Optional. A page token from a previous ListTriggers call."
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "list-executions" help="List executions for a trigger" {
    alias "le"
    arg "id" help="Required. The trigger ID to list executions from. (or use --id)"
    flag "--page-size <page_size>" help="The maximum number of executions to return per page."
    flag "--page-token <page_token>" help="A page token from a previous ListTriggerExecutions call."
    flag "-i --id <id>" help="Required. The trigger ID to list executions from. (or pass it as the [id] argument)"
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "run" help="Run a trigger immediately" {
    arg "id" help="Required. Resource name of the trigger. (or use --id)"
    flag "-i --id <id>" help="Required. Resource name of the trigger. (or pass it as the [id] argument)"
  }
  cmd "update" help="Update a trigger by ID" {
    arg "id" help="Required. Resource name of the trigger. (or use --id)"
    flag "-i --id <id>" help="Required. Resource name of the trigger. (or pass it as the [id] argument)"
    flag "--display-name <display_name>" help="Optional. The display name of the trigger."
    flag "-s --status <status>" help="Optional. The status of the trigger. (options: active, paused, error)"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
}
cmd "tts" help="Text to speech (gemini-3.8-flash-tts)" {
  arg "text" help="Text to speak" required=#true var=#true
  flag "-f --file <file>" help="Read the input text from a file"
  flag "--language <language>" help="BCP-47 language code hint for the speech (e.g. en-US)"
  flag "-m --model <model>" help="Override model (default: gemini-3.8-flash-tts) — tts-capable models: https://ai.google.dev/gemini-api/docs/models"
  flag "--multi-speaker <multi_speaker>" help="Speaker→voice map for two-speaker scripts, e.g. \"Alice=Kore,Bob=Puck\"; start each turn with its speaker label (\"Alice: …\")"
  flag "--out <out>" help="Output file or directory; the extension follows the audio (default: ./gemini-tts-<unix-ms>-<random>.wav)"
  flag "--stdin" help="Read the input text from stdin"
  flag "-v --voice <voice>" help="Voice for single-speaker audio (e.g. Kore, Puck, Zephyr, Charon, Fenrir, Aoede)"
}
cmd "video" help="Generate & edit video conversationally (gemini-omni-1.1-flash)" {
  arg "prompt" help="Video prompt (create input; omit with --resume)" var=#true
  flag "--body <body>" help="Request body as JSON (advanced; merges with intent inputs, rejecting duplicate keys). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
  flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  flag "--aspect-ratio <aspect_ratio>" help="Aspect ratio of the output video (e.g. 16:9, 9:16)" {
    suggestions "16:9" "9:16"
  }
  flag "-m --model <model>" help="Override the video model (e.g. gemini-omni-flash-preview, default: gemini-omni-1.1-flash)" default="gemini-omni-1.1-flash" {
    suggestions "gemini-omni-1.1-flash" "gemini-omni-flash-preview"
  }
  flag "--previous-interaction-id <previous_interaction_id>" help="Continue from an earlier interaction, extending or editing the video it produced"
  flag "--resolution <resolution>" help="Resolution of the output video (defaults to 720p) (e.g. 360p, 720p, 1080p, 4k)" {
    suggestions "360p" "720p" "1080p" "4k"
  }
  flag "--out <path>" help="Write the video to this file (or into this directory). Default: ./gemini-video-{timestamp}-{rand}.{ext}"
  flag "--raw-response" help="Print the raw API response instead of writing the video to a file"
  flag "--resume <id>" help="Resume polling an existing operation by ID instead of creating one"
  flag "--async" help="Return the operation handle without waiting for a terminal response"
  flag "--poll-interval <duration>" help="Override the initial polling interval (positive Go duration, for example 500ms or 2s)"
  flag "--poll-timeout <duration>" help="Override the overall polling deadline (positive Go duration, at least the effective poll interval)"
  flag "-i --input <input...>" help="Local path, files/<id>, or YouTube URL to include as input (repeatable)" var=#true
  flag "--mime-type <mime_type>" help="Override the detected MIME type (one --input only)"
  flag "--stdin" help="Read prompt text from stdin to EOF instead of a JSON body (sent before the positional prompt, if any)"
}
cmd "webhooks" help="Manage webhook endpoints and signing secrets for event delivery" {
  cmd "create" help="Create a webhook endpoint" {
    flag "-n --name <name>" help="Optional. The user-provided name of the webhook."
    flag "-s --subscribed-events <subscribed_events>" help="Required. The events that the webhook is subscribed to. (options: batch.succeeded, batch.expired, batch.failed, interaction.requires_action, interaction.completed, interaction.failed, video.generated) (JSON array) [required]"
    flag "-u --uri <uri>" help="Required. The URI to which webhook events will be sent. [required]"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "delete" help="Delete a webhook by ID" {
    arg "id" help="Required. The ID of the webhook to delete. (or use --id)"
    flag "-i --id <id>" help="Required. The ID of the webhook to delete. (or pass it as the [id] argument)"
  }
  cmd "get" help="Get a webhook by ID" {
    arg "id" help="Required. The ID of the webhook to retrieve. (or use --id)"
    flag "-i --id <id>" help="Required. The ID of the webhook to retrieve. (or pass it as the [id] argument)"
  }
  cmd "list" help="List webhook endpoints" {
    flag "--page-size <page_size>" help="""
      Optional. The maximum number of webhooks to return. The service may return
      fewer than this value. If unspecified, at most 50 webhooks will be
      returned. The maximum value is 1000.
      """
    flag "--page-token <page_token>" help="""
      Optional. A page token, received from a previous 'ListWebhooks' call.
      Provide this to retrieve the subsequent page.
      """
    flag "-a --all" help="Automatically paginate and fetch all results (streams NDJSON for JSON output)"
    flag "--max-pages <max_pages>" help="Maximum number of pages to fetch when using --all (0 = no limit)" default=0
  }
  cmd "ping" help="Send a ping event to a webhook" {
    arg "id" help="Required. The ID of the webhook to ping. (or use --id)"
    flag "-i --id <id>" help="Required. The ID of the webhook to ping. (or pass it as the [id] argument)"
    flag "--body <body>" help="Request body as JSON. Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "rotate-signing-secret" help="Rotate the signing secret for a webhook" {
    alias "rss"
    arg "id" help="Required. The ID of the webhook for which to generate a signing secret. (or use --id)"
    flag "-i --id <id>" help="Required. The ID of the webhook for which to generate a signing secret. (or pass it as the [id] argument)"
    flag "-r --revocation-behavior <revocation_behavior>" help="Optional. The revocation behavior for previous signing secrets. (options: revoke_previous_secrets_after_h24, revoke_previous_secrets_immediately)"
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
  cmd "update" help="Update a webhook by ID" {
    arg "id" help="Required. The ID of the webhook to update. (or use --id)"
    flag "-i --id <id>" help="Required. The ID of the webhook to update. (or pass it as the [id] argument)"
    flag "--update-mask <update_mask>" help="Optional list of fields to update."
    flag "-n --name <name>" help="Optional. The user-provided name of the webhook."
    flag "--state <state>" help="Optional. The state of the webhook. (options: enabled, disabled, disabled_due_to_failed_deliveries)"
    flag "--subscribed-events <subscribed_events>" help="Optional. The events that the webhook is subscribed to. (options: batch.succeeded, batch.expired, batch.failed, interaction.requires_action, interaction.completed, interaction.failed, video.generated) (JSON array)"
    flag "--uri <uri>" help="Optional. The URI to which webhook events will be sent."
    flag "--body <body>" help="Request body as JSON (alternative to individual flags). Can also be provided via stdin; @path reads a file, @- reads stdin to EOF. Use --schema to print the exact JSON Schema."
    flag "--schema" help="Print the exact JSON Schema of the request body and exit"
  }
}
cmd "whoami" help="Display current authentication and global parameter configuration"
cmd "completion" help="Generate the autocompletion script for the specified shell" {
  cmd "bash" help="Generate the autocompletion script for bash" {
    flag "--no-descriptions" help="disable completion descriptions"
  }
  cmd "fish" help="Generate the autocompletion script for fish" {
    flag "--no-descriptions" help="disable completion descriptions"
  }
  cmd "powershell" help="Generate the autocompletion script for powershell" {
    flag "--no-descriptions" help="disable completion descriptions"
  }
  cmd "zsh" help="Generate the autocompletion script for zsh" {
    flag "--no-descriptions" help="disable completion descriptions"
  }
}
cmd "explore" help="Interactively browse and run commands"
cmd "help" help="Help about any command"
cmd "version" help="Print the CLI version"