Joining a project with a few hundred files and no one to ask is slow. You open the folder, scroll the tree, and guess which file matters. google-gemini/gemini-cli is an open-source agent that runs in your terminal, reads the repo you start it in, and answers questions about it in plain language.
This walkthrough follows the README: install, set a key, start it in a repo, and ask for an architecture summary.
A note on availability first
The README opens with a notice. Unpaid-tier and Google One users were moved to Antigravity CLI on June 18, 2026, and the README says Gemini CLI is not optimized for the newest Gemini models. The path below uses an API key or Vertex AI, which the README still documents. If you only have a free consumer login, check the notice before you start.
Install
You do not need to install anything to try it:
npx @google/gemini-cli
To keep it around, install globally with npm or Homebrew:
npm install -g @google/gemini-cli
# or on macOS and Linux
brew install gemini-cli
The README also lists MacPorts and a conda route for restricted environments. If you want a specific channel, @preview, @latest and @nightly tags exist. Stay on latest unless you are testing.
Set your key
The README gives three auth options: Google sign-in, a Gemini API key, and Vertex AI. The API key route is the simplest to script:
# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini
Keep the key in your shell environment, not in the repo. Do not paste it into a file you might commit.
Start it in the repo
From the project root, run:
cd your-project
gemini
If the architecture spans sibling folders, such as a shared library and a docs folder, include them when you start:
gemini --include-directories ../lib,../docs
Now ask the questions you would ask a teammate:
> Explain the architecture of this codebase
> Where are the entry points?
> Which module looks riskiest to change, and why?
The README's own example for existing code is a summary of recent changes: clone a repo, run gemini, and ask "Give me a summary of all of the changes that went in yesterday".
Run it without the interactive screen
For a one-off answer you can save to a file, use the non-interactive flag:
gemini -p "Explain the architecture of this codebase" > ARCHITECTURE_NOTES.md
The README also documents --output-format json for structured output and --output-format stream-json for newline-delimited events. If you want a specific model, pass -m, for example gemini -m gemini-2.5-flash.
Hand the whole thing to an agent
If you already use a coding agent, this prompt covers the same steps: "In this repo, run google-gemini/gemini-cli with my GEMINI_API_KEY from the environment and ask it to explain the architecture, the entry points and the riskiest module. Paste its answer in a file ARCHITECTURE_NOTES.md."
Tips
- Ask narrow follow-ups. "Which files touch authentication?" beats "explain everything".
- Treat the summary as a map, then open the files it names and check them.
- Add only the folders you need with
--include-directories, so the answer stays on topic. - Commit nothing the tool writes until you have read it.
Caveats
- The README says it is not tuned for the latest Gemini models, so answers may differ from what Google's newest tools give.
- Model calls on a key are billed to your account at your tier's rates.
- We followed the README and have not run this end to end for this post.
The step-by-step version is on our use-case page: ask Gemini to explain a codebase from the terminal. For other agents to compare, see the best AI coding agents.
Want the setup commands for 50 AI repos people actually ship with? Get the free AI Repos That Actually Ship pack: https://dedupedai.com/ship-pack/?utm_source=devto&utm_medium=article&utm_campaign=shippack
Top comments (0)