How To Install Gemini CLI on Debian 13
Gemini CLI transforms terminal environments into powerful AI-assisted workspaces, bringing Google’s advanced artificial intelligence directly to the command line. Debian 13 “Trixie,” released in August 2025, provides an excellent foundation for running this cutting-edge development tool. This comprehensive guide covers everything needed to successfully install, configure, and optimize Gemini CLI on Debian 13 systems.
The integration of AI-powered assistance into terminal workflows represents a significant advancement in developer productivity tools. Whether debugging code, generating documentation, or automating DevOps tasks, Gemini CLI offers capabilities that streamline development processes across various programming languages and frameworks. This installation tutorial ensures compatibility with Debian 13’s latest features while addressing common configuration challenges.
What is Gemini CLI?
Gemini CLI serves as an open-source AI agent that brings Google’s Gemini artificial intelligence models directly into terminal environments. This revolutionary tool transforms traditional command-line workflows by providing intelligent assistance for coding, debugging, and project management tasks without requiring constant context switching between applications.
Core Features and Capabilities
The platform offers extensive built-in functionality including GoogleSearch integration for real-time web research, WebFetch capabilities for content retrieval, and comprehensive file management through ReadFile and WriteFile operations. Advanced users benefit from Model Context Protocol (MCP) server support, enabling seamless integration with external tools and services like GitHub repositories, database systems, and Google Workspace applications.
Interactive and non-interactive execution modes provide flexibility for different use cases. Interactive sessions enable conversational AI assistance, while non-interactive commands support automation and scripting workflows. The tool handles large codebases efficiently, supporting over one million tokens in context windows for comprehensive project analysis.
Benefits for Developers
Gemini CLI excels at code explanation and debugging assistance, automatically identifying issues and suggesting improvements across multiple programming languages. The platform generates automated tests, creates comprehensive documentation, and performs intelligent file analysis to understand project structures and dependencies.
Web research capabilities integrate seamlessly into development workflows, allowing developers to query current information, documentation, and best practices without leaving the terminal environment. This integration significantly reduces context switching overhead while maintaining focus on active development tasks.
Debian 13 System Requirements
Hardware Requirements
Debian 13 “Trixie” requires minimum hardware specifications to ensure optimal Gemini CLI performance. System requirements include 2GB RAM minimum with 4GB+ recommended for smooth operation, especially when processing large codebases or multiple concurrent AI requests. Storage allocation should provide 20GB minimum disk space, though 50GB+ proves more practical for desktop installations with development tools and project repositories.
The system architecture must support x86_64 (64-bit) processors, as Debian 13 officially discontinued i386 support in this release. Network connectivity remains essential for installation, updates, and real-time AI model access during Gemini CLI operations.
Supported Architectures
Debian 13 maintains official support across multiple processor architectures including amd64, arm64, armhf, ppc64el, s390x, and the newly added riscv64 platform. This broad compatibility ensures Gemini CLI installation succeeds across diverse hardware configurations, from traditional x86 systems to modern ARM-based development machines and specialized enterprise architectures.
Software Prerequisites
Essential software dependencies include Node.js version 18 minimum, though version 20+ provides optimal compatibility and performance improvements. The Node Package Manager (npm) handles Gemini CLI installation and dependency management across all supported platforms.
Terminal environment compatibility spans bash, zsh, and fish shells, ensuring broad user preference accommodation. Git installation, while optional, enhances development workflow integration and enables advanced MCP server configurations for repository management.
Prerequisites Installation
Installing Node.js on Debian 13
Method 1: APT Package Manager (Simplest Approach)
The default Debian repository provides straightforward Node.js installation through the standard package management system. This method ensures system compatibility and automatic security updates through regular Debian maintenance cycles.
sudo apt update
sudo apt install nodejs npm
node --version # Verify installation success
npm --version # Confirm npm availabilityThis approach installs Node.js version 18, which meets minimum requirements but may lack latest features available in newer releases.
Method 2: NodeSource Repository (Latest Version)
Installing from NodeSource repository provides access to current Node.js releases with enhanced performance and security improvements. This method proves particularly valuable for development environments requiring cutting-edge JavaScript runtime features.
# Add NodeSource repository for latest LTS
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
# Install current Node.js version
sudo apt-get install -y nodejs
# Verify updated installation
node --version
npm --versionThe NodeSource approach automatically handles dependency resolution and provides optimized packages specifically compiled for Debian systems.
Method 3: Node Version Manager (NVM)
NVM enables flexible Node.js version management, allowing multiple versions on single systems and easy switching between projects with different requirements. This method proves invaluable for developers managing multiple projects or testing compatibility across Node.js versions.
# Download and install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
# Reload shell environment
source ~/.bashrc
# Install latest LTS Node.js
nvm install --lts
nvm use --lts
# Verify installation
node --version
npm --versionNVM installations require manual PATH configuration but provide superior flexibility for development environments requiring multiple Node.js versions.
Verifying Prerequisites
Comprehensive verification ensures successful prerequisite installation before proceeding with Gemini CLI setup. Check Node.js version compatibility by confirming version 18+ installation, though version 20+ provides optimal performance and feature access.
Verify npm installation and permissions by testing package installation capabilities and confirming proper PATH configuration. System PATH verification prevents common “command not found” errors during subsequent installation steps.
# Comprehensive verification commands
node --version # Should show v18.0.0 or higher
npm --version # Confirms npm availability
which node # Displays Node.js executable location
which npm # Shows npm binary path
npm config list # Displays current npm configurationInstalling Gemini CLI
Method 1: Global Installation via npm (Recommended)
Global npm installation provides system-wide Gemini CLI access, making the gemini command available from any directory location. This approach suits most development environments where consistent tool availability across projects proves essential.
# Install Gemini CLI globally
sudo npm install -g @google/gemini-cli
# Verify successful installation
gemini --version
# Test command availability
which geminiGlobal installation advantages include persistent command availability across terminal sessions, simplified execution syntax without npx prefixes, and automatic PATH configuration for immediate use. The approach requires sudo privileges but provides the most straightforward user experience.
Consider version management implications when using global installations, as system-wide packages may create conflicts with project-specific requirements. Regular updates through sudo npm update -g @google/gemini-cli maintain security and feature currency.
Method 2: NPX Execution (No Installation)
NPX execution eliminates permanent system modifications while providing full Gemini CLI functionality. This approach proves ideal for testing, occasional use, or environments with strict software installation policies.
# Run without permanent installation
npx https://github.com/google-gemini/gemini-cli
# Alternative GitHub repository syntax
npx @google/gemini-cli
# Direct execution with parameters
npx @google/gemini-cli --helpNPX advantages include guaranteed latest version execution, no root privileges requirements, and zero permanent system footprint. Each execution downloads current packages, ensuring access to newest features and security patches without manual updates.
Disadvantages involve longer startup times due to package downloading, network dependency for each execution, and slightly different command syntax compared to global installations. Consider this method for infrequent use or evaluation purposes.
Method 3: Local Project Installation
Local installation confines Gemini CLI to specific project directories, providing precise version control and avoiding system-wide conflicts. This approach suits development teams requiring consistent tool versions across different projects.
# Create dedicated project directory
mkdir gemini-cli-projects
cd gemini-cli-projects
# Initialize npm project
npm init -y
# Install Gemini CLI locally
npm install @google/gemini-cli
# Execute with npx
npx gemini --versionLocal installations enable package.json dependency management, ensuring reproducible environments across team members and deployment systems. Version pinning through package.json prevents unexpected updates that might disrupt established workflows.
Installation Verification
Comprehensive verification confirms successful installation and identifies potential configuration issues before proceeding with authentication and setup. Test command availability, version information display, and basic functionality access.
# Verify command recognition
gemini --version
# Display help information
gemini --help
# Test basic functionality
echo "Test installation complete" | gemini -p "Summarize this text"Initial Setup and Configuration
First Launch Configuration
Initial Gemini CLI launch presents configuration options that establish user preferences and authentication methods. Theme selection affects terminal appearance and readability, with options including Default, Default Dark, GitHub Dark, Default Light, GitHub Light, and Google Code themes.
Theme persistence occurs through settings.json configuration files, allowing customization at user, workspace, and system levels. Selection affects syntax highlighting, interface elements, and overall visual presentation during AI interactions.
# Launch Gemini CLI for initial setup
gemini
# Follow prompts for theme selection
# Choose preferred visual appearance
# Complete authentication processAuthentication Methods
Personal Google Account (Recommended)
Google account authentication provides the most streamlined experience with generous free tier limitations. Browser-based OAuth flow ensures secure credential handling while enabling access to Gemini 2.5 Pro with one million token context windows.
Free tier includes 60 requests per minute and 1,000 requests daily at no charge, sufficient for most development workflows. Authentication persists across sessions, eliminating repeated login requirements during regular use.
# Initiate Google authentication
# Select "Personal Google Account" option
# Complete browser-based OAuth flow
# Grant necessary permissions
# Return to terminal for confirmationAPI Key Method
Direct API key configuration provides alternative authentication for automated systems or environments restricting interactive browser access. Obtain keys through Google AI Studio with appropriate project configuration and usage limits.
# Set API key environment variable
export GEMINI_API_KEY="your_api_key_here"
# Add to shell profile for persistence
echo 'export GEMINI_API_KEY="your_key"' >> ~/.bashrc
source ~/.bashrcGoogle Cloud Vertex AI
Enterprise environments benefit from Vertex AI authentication, providing enhanced security, audit capabilities, and integration with existing Google Cloud infrastructure. Configuration requires project ID specification and regional endpoint selection.
Settings Configuration
Settings File Locations and Hierarchy
Gemini CLI employs hierarchical configuration management through multiple settings.json files with specific precedence rules. System settings (/etc/gemini-cli/settings.json) provide baseline configuration, user settings (~/.gemini/settings.json) establish personal preferences, and workspace settings (.gemini/settings.json) enable project-specific customization.
Configuration inheritance follows precedence from workspace to user to system levels, allowing granular control over tool behavior across different contexts and projects.
Basic Settings Structure
{
"theme": "Default Dark",
"selectedAuthType": "oauth-personal",
"timeout": 30000,
"model": "gemini-2.5-pro"
}Directory Structure Setup
Proper directory organization enhances Gemini CLI functionality and project management capabilities. Create workspace directories for project-specific configurations and establish consistent folder structures for efficient tool operation.
# Create Gemini CLI workspace
mkdir -p ~/gemini-cli-workspace
cd ~/gemini-cli-workspace
# Initialize workspace configuration
mkdir .gemini
# Create basic settings file
echo '{"theme": "Default"}' > .gemini/settings.jsonTroubleshooting Common Issues
Node.js Version Conflicts
Problem Identification
Debian 13 ships with Node.js version 18 by default, while Gemini CLI performs optimally with version 20 or higher. Version conflicts manifest as installation failures, runtime errors, or limited functionality access during CLI operations.
Resolution Strategy
# Check current Node.js version
node --version
# If version < 20, upgrade via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Verify upgrade success
node --version
npm --versionAlternative resolution involves NVM installation for flexible version management without system-wide changes. This approach proves particularly valuable in multi-user environments or systems requiring multiple Node.js versions.
npm Command Not Found
Symptom Analysis
The “npm: command not found” error indicates missing npm installation or PATH configuration issues. This problem commonly occurs after Node.js installation methods that exclude npm or during incomplete installation processes.
Comprehensive Troubleshooting
# Verify npm installation status
sudo npm -v 2>/dev/null || echo "npm not found"
which npm || echo "npm not in PATH"
# Install npm if missing
sudo apt install npm -y
# Check PATH configuration
echo $PATH | grep -q npm && echo "npm in PATH" || echo "PATH issue detected"
# Add npm to PATH if necessary
export PATH="$PATH:/usr/local/bin"
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrcPermission issues may prevent npm execution even when properly installed. Resolve through ownership correction or npm configuration adjustments for non-root access.
# Fix npm permissions
sudo chown -R $(whoami):$(whoami) ~/.npm
# Configure npm for non-root global installs
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATHInstallation Permission Errors
Global Installation Challenges
Global npm installations require elevated privileges, potentially creating security concerns or access restrictions in managed environments. Permission errors during sudo npm install -g commands indicate system policy restrictions or filesystem permission conflicts.
Alternative Solutions
NPX usage eliminates global installation requirements while maintaining full functionality access. This approach bypasses permission restrictions and provides consistent execution across different system configurations.
# Use npx instead of global install
npx @google/gemini-cli --version
# Create alias for convenience
echo 'alias gemini="npx @google/gemini-cli"' >> ~/.bashrc
source ~/.bashrcShared Folder Problems
Virtual machine environments with shared folders may encounter symlink restrictions preventing proper package installation. These limitations affect npm’s dependency management and can cause installation failures or runtime errors.
# Install in non-shared directory
mkdir ~/local-gemini
cd ~/local-gemini
npm install @google/gemini-cli
# Create execution script
echo '#!/bin/bash\ncd ~/local-gemini && npx gemini "$@"' > ~/bin/gemini
chmod +x ~/bin/geminiAuthentication Failures
Google Account Issues
Authentication problems typically involve browser workflow interruptions, network connectivity restrictions, or account permission conflicts. Corporate firewalls or proxy configurations may prevent successful OAuth completion.
Network-related Solutions
# Test network connectivity
curl -I https://accounts.google.com
# Configure proxy if necessary
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# Alternative: use API key authentication
export GEMINI_API_KEY="your_api_key_from_ai_studio"Account Permission Troubleshooting
Verify Google account access to AI services and confirm organizational policies allow external AI tool connections. Some enterprise accounts restrict third-party application access through administrative controls.
Performance and Connectivity
Network-related Optimization
Corporate environments may require proxy configuration for external API access. DNS resolution problems can cause connection timeouts or authentication failures during initial setup or runtime operations.
# Configure npm proxy settings
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy https://proxy.example.com:8080
# Test connectivity
ping api.google.com
nslookup generativelanguage.googleapis.comConnection Timeout Adjustments
Increase timeout values for environments with limited bandwidth or high network latency. Configuration adjustments prevent premature connection termination during large file processing or complex AI operations.
Advanced Configuration
Model Context Protocol (MCP) Servers
Understanding MCP Integration
Model Context Protocol servers extend Gemini CLI capabilities through specialized tool integration, enabling connections to external services like GitHub repositories, database systems, and documentation platforms. MCP architecture provides standardized interfaces for AI model interaction with various data sources and services.
Popular MCP servers include GitHub integration for repository management, Context7 for up-to-date documentation access, and specialized database connectors for BigQuery and Firestore operations. Custom MCP server development enables organization-specific tool integration and workflow automation.
GitHub MCP Server Configuration
{
"mcpServers": {
"github": {
"httpUrl": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer YOUR_GITHUB_PAT"
},
"timeout": 5000,
"retry": 3
}
}
}GitHub integration enables repository browsing, issue management, and pull request operations directly through Gemini CLI interactions. Personal Access Token (PAT) configuration provides secure authentication for private repository access.
Database and Workspace Integration
{
"mcpServers": {
"bigquery": {
"httpUrl": "https://bigquery.googleapis.com/mcp/",
"headers": {
"Authorization": "Bearer YOUR_GCP_TOKEN"
}
},
"context7": {
"httpUrl": "https://context7.com/api/mcp/",
"timeout": 10000
}
}
}Custom Commands and Workflows
Creating Custom Slash Commands
Gemini CLI supports custom command creation through TOML configuration files stored in ~/.gemini/commands/ or .gemini/commands/ directories. Custom commands enable workflow automation and template-based AI interactions tailored to specific development tasks.
Example Custom Command Structure
# ~/.gemini/commands/plan.toml
description = "Creates comprehensive implementation plans"
prompt = """
Create a detailed implementation plan for: {{args}}
Include the following sections:
1. Technical requirements analysis
2. Architecture design decisions
3. Implementation timeline
4. Risk assessment and mitigation
5. Testing strategy
6. Deployment considerations
Format the response with clear headings and actionable steps.
"""Template placeholders enable dynamic argument handling, allowing custom commands to accept user input and generate contextually appropriate responses. Command discovery occurs automatically, making new commands available immediately after file creation.
Project-Specific Configuration
GEMINI.md Context Files
Project-specific instructions through GEMINI.md files provide contextual information for AI interactions within specific codebases. These files enable coding style enforcement, framework-specific guidance, and project architecture understanding across development team members.
# Project: E-commerce Platform
## Architecture
- React frontend with TypeScript
- Node.js Express backend
- PostgreSQL database
- Redis for caching
## Coding Standards
- Use functional components with hooks
- Implement comprehensive error handling
- Follow ESLint configuration
- Maintain 90%+ test coverage
## Dependencies
- Avoid adding new dependencies without team approval
- Prefer established libraries with active maintenance
- Document all third-party integrationsSettings Inheritance and Precedence
Configuration hierarchy enables granular control over Gemini CLI behavior across different contexts. System-wide settings establish baseline functionality, user settings provide personal preferences, and workspace settings enable project-specific customization with clear precedence rules.
# Settings file locations in precedence order
/etc/gemini-cli/settings.json # System-wide (lowest precedence)
~/.gemini/settings.json # User-specific
./.gemini/settings.json # Workspace-specific (highest precedence)Performance Optimization
Model Selection Strategies
# Use Gemini 2.5 Flash for faster responses
gemini -m "gemini-2.5-flash" -p "Quick code review"
# Use Gemini 2.5 Pro for complex analysis
gemini -m "gemini-2.5-pro" -p "Analyze entire codebase architecture"Model selection impacts response time, accuracy, and token consumption. Flash models provide rapid responses for simple queries, while Pro models offer enhanced capabilities for complex reasoning and large context analysis.
Request Timeout Configuration
Customize timeout settings for different MCP servers and network conditions. Extended timeouts accommodate slower connections or complex processing requirements, while reduced timeouts prevent unnecessary waiting during network issues.
{
"defaultTimeout": 30000,
"mcpServers": {
"github": {"timeout": 15000},
"database": {"timeout": 45000}
}
}Security Considerations
Authentication Security
Google Account Best Practices
Personal versus workspace Google account selection affects data access, usage limits, and administrative control. Personal accounts provide individual management and generous free tiers, while workspace accounts enable organizational oversight and enhanced security controls.
Two-factor authentication strengthens account security and prevents unauthorized access to AI capabilities. Regular token rotation and access monitoring provide additional security layers for sensitive development environments.
API Key Management
Environment variable storage prevents hardcoded credentials in configuration files or version control systems. Proper key rotation schedules and access monitoring ensure ongoing security compliance in development and production environments.
# Secure API key configuration
export GEMINI_API_KEY="your_secure_key"
# Add to secure shell profile
echo 'export GEMINI_API_KEY="your_key"' >> ~/.profile
# Avoid version control inclusion
echo 'GEMINI_API_KEY' >> .gitignorePermission Management
Tool Execution Permissions
Gemini CLI presents permission prompts for tool execution, requiring user confirmation for file operations, web searches, and external service access. “Allow once” versus “Allow always” decisions balance convenience with security oversight for different operation types.
YOLO mode eliminates permission prompts but increases security risks through unrestricted tool access. Reserve this mode for trusted environments with appropriate access controls and monitoring systems.
File System Security
Understanding file read/write permissions prevents unauthorized access to sensitive information. Workspace isolation through proper directory configuration limits AI access to intended project files while protecting system configurations and personal data.
# Create isolated workspace
mkdir ~/secure-gemini-workspace
cd ~/secure-gemini-workspace
# Set restrictive permissions
chmod 700 ~/secure-gemini-workspace
# Configure workspace-specific settings
echo '{"restrictFileAccess": true}' > .gemini/settings.jsonNetwork Security
MCP Server Communications
HTTPS requirements for remote MCP servers ensure encrypted communication channels and prevent credential interception during authentication processes. Authentication header security and certificate verification provide additional protection layers for external service integration.
Corporate network environments may require proxy configuration and certificate management for proper security compliance. Coordinate with network administrators to ensure appropriate access controls while maintaining functionality.
Testing Your Installation
Basic Functionality Tests
Command Availability Verification
# Verify installation success
gemini --version
# Display available options
gemini --help
# Test command recognition
which gemini || echo "Command not found in PATH"Successful installation displays version information and help text without errors. Command recognition verification ensures proper PATH configuration and executable permissions for all user accounts requiring access.
Interactive Mode Testing
# Launch interactive session
gemini
# Test basic AI interaction
> What is the current date and time?
# Test file operations
> List files in the current directory
# Exit interactive mode
> exitInteractive mode testing confirms authentication status, AI model connectivity, and basic tool functionality. Successful interactions demonstrate proper configuration and network connectivity for ongoing development use.
Non-Interactive Mode Testing
# Test direct prompt execution
gemini -p "Explain the ls command in Linux"
# Test with specific model
gemini -m "gemini-2.5-flash" -p "Generate a simple Hello World in Python"
# Test file input processing
echo "function test() { return 1; }" | gemini -p "Explain this JavaScript function"Non-interactive testing validates command-line argument handling and batch processing capabilities essential for automation and scripting workflows.
Tool Integration Testing
Built-in Tools Verification
# Launch interactive mode
gemini
# List available tools
> /tools
# Test GoogleSearch functionality
> /search "Debian 13 release notes"
# Test file operations
> /write-file test.txt "Hello, Gemini CLI!"
> /read-file test.txtTool integration testing confirms proper functionality for web search, file operations, and other built-in capabilities. Successful tool execution demonstrates complete installation and configuration correctness.
MCP Server Testing
# Verify MCP server connections
> /mcp
# Test GitHub integration (if configured)
> List my repositories
# Verify authentication status
> /auth statusMCP server testing validates external service integration and authentication configurations. Proper connectivity enables advanced workflow automation and specialized tool access throughout development processes.
Performance Validation
Response time measurement and resource usage monitoring ensure optimal performance characteristics for ongoing development use. Context window utilization testing validates large file processing capabilities and complex project analysis functionality.
# Performance timing test
time gemini -p "Analyze this small code snippet: echo 'hello'"
# Memory usage monitoring
top -p $(pgrep gemini) -n 1Congratulations! You have successfully installed Gemini CLI. Thanks for using this tutorial for installing the latest version of Gemini CLI on Debian 13 “Trixie” Linux. For additional help or useful information, we recommend you check the official Google Gemini website.
