Gemini CLI Tutorial: Setup and Configuration Guide
Coding with AI in your terminal often means bouncing between browser tabs, manual copy-pasting, and disjointed command tracking. This tutorial is designed for software engineers and DevOps practitioners setting up a command-line AI coding agent on Linux using official Google Gemini models. By following this guide, you will have a working terminal environment equipped with persistent authentication, workspace security, and external tool integration.
Before you start
- Ubuntu 22.04 or later (or modern Debian-based Linux)
- Node.js version 20.0.0 or higher
- A Google AI Studio API key or Google Cloud Vertex AI project
Verify Node.js and Install Gemini CLI
Before installing the package, verify that your environment meets the minimum runtime requirements. The CLI requires Node.js version 20.0.0 or later to run its runtime services properly.
Once you confirm your runtime meets the threshold, install the official package globally using the npm command shown below. In our test environment, running these commands completed without errors and made the gemini executable immediately available across the shell path.
# Verify Node.js is version 20.0.0 or higher
node -v
# Install the official Gemini CLI globally
npm install -g @google/gemini-cli
# Verify the installation succeeded
gemini --version
Output from our test run
$ node -v
v22.23.3
$ npm install -g @google/gemini-cli
added 7 packages in 43s
npm notice
npm notice New major version of npm available! 10.9.9 -> 12.2.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.2.0
npm notice To update run: npm install -g [email protected]
npm notice
$ gemini --version
0.62.0
$Understanding Authentication Requirements
Older versions allowed users to sign in directly through consumer Google web logins, but that workflow is no longer supported for this tool. Current releases require either an API key generated from Google AI Studio or project authentication through Google Cloud Vertex AI.
Using a dedicated API key provides a streamlined path for individual developers. Exporting your key through the environment ensures that the agent authenticates automatically without prompting for browser verification.
Configure Environment Variables
To prevent having to re-enter your credentials every time you launch a new terminal, save your key inside your shell profile. You can append the export statement to your bash configuration file.
Add the appropriate export line shown below to your user profile file. If your workflow uses enterprise infrastructure instead, substitute the key export with your Google Cloud project variable before sourcing the file.
export GEMINI_API_KEY="AIzaSyYourActualStudioKeyHere"
# Or for Google Cloud Vertex AI:
# export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
Set Up a Trusted Project Workspace
Recent updates introduce directory boundaries to keep autonomous actions isolated to intended source trees. The agent evaluates directory paths to ensure it only inspects files and runs commands inside trusted locations.
Set up an isolated directory for your work and initialize it with source control. In our Debian sandbox test, creating the workspace directory and running the Git initialization command passed and set up a clean root folder.
mkdir -p ~/gemini-workspace && cd ~/gemini-workspace
git init
Output from our test run
$ mkdir -p ~/gemini-workspace && cd ~/gemini-workspace
$ git init
Initialized empty Git repository in /root/gemini-workspace/.git/
$Configure Project Settings and Permissions
The CLI manages configuration across a hierarchy, reading global defaults from your home directory before applying project-level overrides. Placing a local settings file inside your project root gives you control over autonomous behavior.
The example configuration shown below explicitly trusts the active workspace directory while disabling automated command execution. This setting ensures that the agent pauses and requests confirmation before running shell commands on your system.
{
"general": {
"trustDirectory": true,
"autoApproveCommands": false
},
"model": {
"temperature": 0.2
}
}
Integrate the Model Context Protocol
Native Model Context Protocol support allows the tool to query external services and inspect local system state through specialized extensions. You can configure these integrations directly within your project settings file.
The configuration block below shows how to register a local filesystem server under the servers section. Registering this service provides structured file browsing capabilities across the active repository path.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}
}
}
Inspect Interactive and Piped Execution
The CLI supports both an interactive conversational mode and headless execution for automated pipelines. You can verify available subcommands, extensions, and flags by querying the built-in help documentation.
Testing the help command in our sandbox passed cleanly, printing all available operational options. You can launch an interactive session directly, pass immediate queries using the prompt flag, or pipe terminal data directly into the agent.
gemini --help
Output from our test run
$ gemini --help
Usage: gemini [options] [command]
Gemini CLI - Defaults to interactive mode. Use -p/--prompt for non-interactiv
e (headless) mode.
Commands:
gemini mcp Manage MCP servers
gemini extensions <command> Manage Gemini CLI extensions. [aliases: extension]
gemini skills <command> Manage agent skills. [aliases: skill]
gemini hooks <command> Manage Gemini CLI hooks. [aliases: hook]
gemini gemma Manage local Gemma model routing
gemini [query..] Launch Gemini CLI [default]
Positionals:
query Initial prompt. Runs in interactive mode by default; use -p/--prompt for non-interactive.
Options:
-d, --debug Run in debug mode (open debug console with F12) [boolean] [default: false]
-m, --model Model [string]
-p, --prompt Run in non-interactive (headless) mode with the given prompt. Appended to inpu
t on stdin (if any). [string]
-i, --prompt-interactive Execute the provided prompt and continue in interactive mode [string]
--skip-trust Trust the current workspace for this session. [boolean] [default: false]
-w, --worktree Start Gemini in a new git worktree. If no name is provided, one is generated a
utomatically. [string]
-s, --sandbox Run in sandbox? [boolean]Wrap-up
You now have a verified Gemini CLI setup on Linux, complete with persistent API credentials, workspace boundary enforcement, and MCP server integration. This configuration allows you to safely use Google Gemini models for terminal-driven development while retaining control over system command execution.
FAQ
Why does Gemini CLI fail when logging in with a personal Google account?
Direct consumer Google account and Google One logins are deprecated in Gemini CLI. You must authenticate using an API key from Google AI Studio or a Google Cloud Vertex AI project.
What minimum Node.js version is required?
The CLI requires Node.js version 20.0.0 or higher.
How does the tool prevent unwanted system changes?
The CLI relies on trusted folder boundaries and permission settings in your configuration file, where you can disable automated command approvals so the agent must ask before running commands.