Gemini CLI Container

• Container Architecture
• Building the Container Image
  • Build Arguments
• Authentication Setup
  • Initial Authentication
  • Authentication Persistence
  • Verifying Authentication
  • Authentication via GEMINI_API_KEY
    • When to Use API Key Authentication
    • Obtaining a GEMINI_API_KEY
    • Using API Key with the Container
• Working with Gemini CLI from the Container
  • Basic Usage Pattern
  • Volume Mounts Explained
  • Working Directory Context
• Usage Examples
  • Interactive Session
  • Single Command Execution
  • Processing Files
  • Shell Alias for Convenience
• File Permissions
  • Option 1: Build with Custom UID
  • Option 2: Fix Permissions After Creation
• Troubleshooting
  • Authentication Issues
  • File Access Issues
  • Container Issues

A containerized version of Google's Gemini CLI tool. This container provides a rootless environment for running Gemini CLI commands while maintaining persistent authentication and seamless file access.

Container Architecture

• Rootless execution: Runs as user gemini (UID 1000) instead of root
• Minimal base: Uses node:22-slim which provides a smaller attack surface

Building the Container Image

To build the container image from the provided Dockerfile:

docker build -t gemini-cli:dev .

Build Arguments

The Dockerfile supports customization through build arguments:

docker build \
  --build-arg GEMINI_CLI_VERSION=0.1.17 \
  --build-arg USERNAME=gemini \
  --build-arg UID=1000 \
  --build-arg GID=1000 \
  -t gemini-cli:dev .

Authentication Setup

The Gemini CLI requires authentication with Google's services. Authentication data is stored locally in your HOME directory for persistence across container runs.

Initial Authentication

1. Run the container with HOME directory mapping:

   docker run -it -v $HOME:/home/gemini --rm gemini-cli:dev

2. Follow the authentication prompts that appear when the container starts. The CLI will guide you through the OAuth flow.

3. Authentication storage: Your credentials will be stored in $HOME/.config/gemini-cli/ on your host system, which is mapped to /home/gemini/.config/gemini-cli/ inside the container.

Authentication Persistence

The authentication setup persists because:

• The container maps your host $HOME to /home/gemini inside the container
• Gemini CLI stores credentials in the user's home directory
• Subsequent container runs will reuse the existing authentication

Verifying Authentication

To verify your authentication is working:

docker run -it -v $HOME:/home/gemini --rm gemini-cli:dev --help

If authentication is successful, you should see the Gemini CLI help without authentication prompts.

Authentication via GEMINI_API_KEY

As an alternative to the OAuth flow described above, you can authenticate using a GEMINI_API_KEY environment variable. This method is particularly useful for automation, CI/CD pipelines, and scripting scenarios where interactive authentication is not feasible.

When to Use API Key Authentication

• Automation and scripting: When running Gemini CLI in automated environments
• CI/CD pipelines: For continuous integration and deployment workflows
• Non-interactive environments: Where OAuth browser flow is not available
• Simplified setup: When you prefer a single environment variable over persistent credential storage

Obtaining a GEMINI_API_KEY

1. Google AI Studio (Recommended):

   • Visit Google AI Studio
   • Navigate to the API keys section
   • Create a new API key for your project

2. Google Cloud Console:

   • Access the Google Cloud Console
   • Enable the Gemini API for your project
   • Create credentials and generate an API key

Using API Key with the Container

When using API key authentication, you don't need to map your HOME directory for credential persistence. Simply pass the API key as an environment variable:

Basic usage with API key:

docker run -it -v ${PWD}:/work -e GEMINI_API_KEY=your_actual_api_key --rm gemini-cli:dev

Using environment file for API key:

# Create a .env file with your API key
echo "GEMINI_API_KEY=your_actual_api_key" > .env

# Use the environment file with Docker
docker run -it -v ${PWD}:/work --env-file .env --rm gemini-cli:dev

Note that with API key authentication, the simplified volume mounting only requires -v ${PWD}:/work for file access, making the container commands shorter and more suitable for automation.

Working with Gemini CLI from the Container

For practical usage, you'll want to access files from your current working directory. Use both volume mounts for full functionality:

Basic Usage Pattern

docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev [GEMINI_CLI_ARGS]

Volume Mounts Explained

• -v $HOME:/home/gemini: Maps your home directory for authentication persistence
• -v ${PWD}:/work: Maps your current working directory to the container's working directory
• --rm: Automatically removes the container after execution
• -it: Provides interactive terminal access

Working Directory Context

The container sets /work as the working directory, which corresponds to your current directory (${PWD}) on the host system. This means:

• Files in your current directory are accessible within the container
• Output files created by Gemini CLI will appear in your current directory
• Relative paths work as expected

Usage Examples

Interactive Session

Start an interactive session to run multiple commands:

docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev

Single Command Execution

Run a single Gemini CLI command:

docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev generate "Explain this code" --file ./script.py

Processing Files

Work with files in your current directory:

# Analyze a document
docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev analyze --file ./document.txt

# Generate content and save to file
docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev generate "Create a summary" --output ./summary.txt

Shell Alias for Convenience

Create a shell alias for easier usage:

# Add to your ~/.bashrc or ~/.zshrc
alias gemini='docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev'

# Then use simply:
gemini --help
gemini generate "Hello, world!"

File Permissions

The container runs as user gemini with UID 1000. If your host user has a different UID, you may encounter permission issues. To resolve this:

Option 1: Build with Custom UID

docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t gemini-cli:dev .

Option 2: Fix Permissions After Creation

# If files are created with wrong permissions
sudo chown -R $(id -u):$(id -g) ./output-files

Troubleshooting

Authentication Issues

Problem: Authentication prompts appear on every run Solution: Ensure $HOME is properly mapped and authentication completed successfully

Problem: Permission denied accessing config files Solution: Check that $HOME/.config is writable by your user

File Access Issues

Problem: Cannot access files in current directory Solution: Ensure you're using -v ${PWD}:/work volume mount

Problem: Created files have wrong ownership Solution: Rebuild container with your UID/GID or fix permissions afterward

Container Issues

Problem: Container fails to start Solution: Verify Docker is running and image was built successfully

Problem: Command not found errors Solution: Ensure you're passing arguments after the image name