Gemini CLI
Use Gemini from the terminal to understand code, edit files, and automate development work.
Per-dimension scores and reasoning
Evidence shows: README mentions sandbox, trusted folders, approval modes, but lacks implementation details; security policy (SECURITY.md) and dependency overrides exist, but no vulnerability scanning evidence; external effects (shell commands, file operations) are documented, but user confirmation mechanism not detailed; rollback not mentioned. Deductions: security features are mostly documented claims without code-level evidence; least privilege and user confirmation implementations not shown in provided files.
Evidence shows: CI workflows (agent-session-drift-check.yml) and test files (autogen.test.ts, eval-analysis.test.ts, eval-coverage.test.ts) indicate testing and consistency checks; dependency versions are pinned (exact versions in package.json), but no dependency availability proof; failure messages not evident in provided files. Deductions: limited test coverage, no specific failure message examples.
Evidence shows: README describes multiple use cases (code understanding, automation, GitHub integration) and multiple installation methods (npx, npm, Homebrew, MacPorts, Anaconda); capability boundaries documented (sandbox, trusted folders) but no configuration details; trigger precision (commands, MCP) documented but no implementation details; environment fit (Node.js version, OS) specified. Deductions: insufficient details on capability boundaries and trigger precision.
Evidence shows: README is well-structured with installation, usage, documentation links; installation notes detailed; naming stable (gemini command); examples and FAQ links provided; known limitations not explicitly listed; license Apache-2.0; versioning with changelog link; maintenance responsibility clear (Google and community). Deductions: known limitations section missing, not explicitly listed in README.
Evidence shows: Output usability supported via multiple output formats (json, stream-json); marginal value via free tier, model capabilities, tool integrations; cost-benefit via free tier and open-source license. Deductions: no actual performance or user feedback evidence.
Evidence shows: Claims in README (e.g., free tier, model capabilities) lack specific sources; cross-source verification limited, relying on README and some tests; facts and inferences not clearly separated. Deductions: lack of independent verification and source citations.
- Security features (sandbox, trusted folders, approval modes) are mentioned in README but lack implementation details; further code review needed.
- Dependency security is only evidenced by overrides; no vulnerability scanning or audit evidence provided.
- Rollback mechanism not mentioned; users should be aware of irreversible operations.
- Known limitations not explicitly listed in README; users may encounter unexpected issues.
What does this agent do, and when should you use it?
Gemini CLI is an open-source, terminal-first AI agent whose model service is provided by Gemini. It accepts natural-language tasks in an interactive CLI and can work with local files, execute shell commands, fetch web pages, and ground responses with Google Search. It can inspect and edit large codebases, use PDFs, images, or sketches as multimodal inputs, and load persistent project context from GEMINI.md. For automation, its headless mode emits plain text, JSON, or newline-delimited stream-json events; a separate Gemini CLI GitHub Action brings related tasks into GitHub workflows. Its primary deployment boundary is the machine or script environment running the CLI, and model access requires Google sign-in, a Gemini API key, or Vertex AI credentials.
After the user starts gemini, the CLI operates on the current directory or additional paths supplied with --include-directories. It combines repository files and GEMINI.md context with Gemini, then can invoke its File System Operations, Shell Commands, Web Fetch, and Google Search capabilities; MCP servers configured in ~/.gemini/settings.json can add external tools. Documented operations include querying and editing codebases, generating code, debugging problems, handling complex rebases, and building applications from PDFs, images, or sketches. Interactive sessions return results in the terminal, while headless execution accepts prompts through -p and produces text, --output-format json, or --output-format stream-json output. Checkpointing can preserve and resume sessions, while the Gemini CLI GitHub Action supports pull-request reviews, issue triage, and assistance triggered by @gemini-cli mentions.
- A developer joining an unfamiliar large repository can ask for an architectural explanation, summaries of recent changes, and help locating relevant code.
- An engineer fixing a defect from the terminal can have the agent edit files, run shell commands, and continue troubleshooting from command results.
- A prototype builder with a PDF, interface image, or sketch can use the documented multimodal path to generate an initial application.
- A team maintaining automation scripts can use
gemini -pwith JSON or stream-json output to integrate code analysis and operational tasks into existing workflows. - A GitHub-based project can adopt the separate Gemini CLI GitHub Action for pull-request reviews, issue labeling and prioritization, or mention-triggered assistance.
- A team with internal systems can configure MCP servers to expose specialized capabilities such as databases, collaboration services, or media-generation systems.
What are this agent's strengths and limitations?
- File operations, shell execution, web fetching, and Google Search grounding are available in the terminal, allowing a task to progress from analysis to concrete code operations.
- Interactive use, plain-text headless output, structured JSON, and streaming NDJSON events cover both human-driven sessions and script automation.
- MCP support, Custom Extensions, and Custom Commands provide documented ways to connect specialized capabilities and package reusable workflows.
- Multimodal inputs include PDFs, images, and sketches, while the CLI is explicitly designed to query and edit large codebases.
- Checkpointing, GEMINI.md context, documented sandboxing and trusted-folder controls, and a separate GitHub Action address several parts of the development lifecycle.
- Core operation is tied to Gemini models and Google's authentication paths; no native OpenAI or Anthropic model-provider adapter is documented.
- File editing and shell execution expose the local development environment, so adopters need to establish appropriate sandboxing, trusted-folder, and execution policies.
- Google sign-in, Gemini API keys, and Vertex AI have different quotas, billing models, and project settings, creating an authentication-governance decision for teams.
- Preview releases may contain regressions, and nightly releases are described as having pending validation, making unreviewed upgrades risky for critical automation.
- MCP and GitHub integration require separate configuration: MCP servers must be added to
~/.gemini/settings.json, and GitHub workflows use a distinct Gemini CLI GitHub Action.
How do you install or deploy this agent?
Use an environment capable of running Node.js/npm and connecting to Gemini services. To run without a permanent installation, execute npx @google/gemini-cli. For a global installation, execute npm install -g @google/gemini-cli; macOS and Linux users can also run brew install gemini-cli, and macOS supports sudo port install gemini-cli. In a restricted environment, run conda create -y -n gemini_env -c conda-forge nodejs, conda activate gemini_env, and npm install -g @google/gemini-cli. After installation, authenticate by starting gemini and selecting Google sign-in, or set GEMINI_API_KEY="YOUR_API_KEY". For Vertex AI, set GOOGLE_API_KEY="YOUR_API_KEY" and GOOGLE_GENAI_USE_VERTEXAI=true; users of an organizational Code Assist license should also set GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID".
How do you use this agent?
Open the target project directory, run gemini, complete browser authentication or use credentials already present in the environment, and enter a task. To expose more directories, run gemini --include-directories ../lib,../docs; to select a documented model explicitly, run gemini -m gemini-2.5-flash. For scripts, run gemini -p "Explain the architecture of this codebase". Add --output-format json for structured output or --output-format stream-json for newline-delimited events from a long-running operation. Configure external MCP servers in ~/.gemini/settings.json, place persistent project context in GEMINI.md, and use checkpointing when a complex conversation must be saved and resumed.
FAQ
Is payment required?
What local resources can it access?
--include-directories, and it can execute shell commands. Teams should evaluate the documented sandboxing and trusted-folder controls before granting it access to sensitive repositories or environments.Can it run in CI or another non-interactive environment?
gemini -p and supports text, JSON, and stream-json output. GitHub workflows can use the separate Gemini CLI GitHub Action, but the environment still needs a configured authentication method.Can it connect to internal tools?
~/.gemini/settings.json, and the project also documents Custom Extensions and Custom Commands. Actual permissions and operations depend on the connected servers and their configuration.Which release channel is appropriate for production work?
latest stable channel is the safer documented choice for critical workflows. Weekly preview builds may contain regressions, while daily nightly builds should be assumed to include changes with pending validation.