Skip to main content
@google/gemini-cli (v0.40.1+).

​
Install

npm install -g @google/gemini-cli

​
Auth

Env varSource
GEMINI_API_KEYAI Studio (canonical)
GOOGLE_API_KEYVertex AI (also accepted)
Crewship’s apiKeyEnvVarsForAdapter("GEMINI_CLI") accepts either; both are mirrored to the container env so any version of gemini-cli finds its key.

​
Models

API stringTier
gemini-3-1-profrontier
gemini-3-1-flashfast
gemini-3-1-flash-litecheap
gemini-2-5-profrontier — Crewship default (stable GA)
gemini-2-5-flashfast
gemini-2-5-flash-litecheap
gemini-2.0-flash and gemini-1.5-pro are not available in the current Gemini API catalog — removed from picker. Note the dash-separated ID format (gemini-3-1-pro, not gemini-3.1-pro); Google’s models.list endpoint returns this canonical form.

​
Command shape

gemini -p "[SYSTEM]\n<preamble>\n\n[USER]\n<msg>" --output-format stream-json -m <model>
  • -p — non-interactive prompt mode
  • --output-format stream-json — JSONL events (PR #10883)
  • -m — model selector
  • System prompt folded into prompt body since headless mode has no --system-instruction flag

​
MCP

Configured at /output/<slug>/.gemini/settings.json: 
{
  "mcpServers": {
    "linear": {
      "httpUrl": "https://mcp.linear.app/sse",
      "headers": {"Authorization": "Bearer ${LINEAR_TOKEN}"}
    },
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/work"],
      "env": {"FOO": "${FOO}"}
    }
  }
}
Crewship prefers httpUrl (HTTP streaming, current) over url (SSE, legacy). Env-var syntax ${VAR} or $VAR (POSIX); both expanded by gemini-cli at MCP spawn.

​
Memory

Canonical memory set including GEMINI.md (Gemini’s auto-discovery path) at /output/<slug>/.

​
Output stream

JSONL per geminicli.com/docs/cli/headless:
EventNotes
initsession bootstrap
messageassistant text — delta for streaming, content for full
tool_usetool_name, tool_id, parameters (snake_case canonical, NOT name/id/input)
tool_resulttool_id (NOT tool_use_id), status, output
errorseverity: warning demoted to system event, severity: error is fatal
resultstats.{total_tokens, input_tokens, output_tokens, duration_ms, tool_calls}

​
Troubleshooting

gemini: not found — npm install failed. Auth precedence trap — if both GEMINI_API_KEY (AI Studio) and GOOGLE_API_KEY (Cloud) are in the env, GOOGLE wins silently. Use one or the other. Exit code 52 with no JSON — auth failure (issue #20183). Orchestrator detects exit-without-result and surfaces as run error.