{"id":30108960,"url":"https://github.com/ophiosdev/gemini-cli-container","last_synced_at":"2025-08-10T03:19:49.987Z","repository":{"id":308959929,"uuid":"1034713184","full_name":"ophiosdev/gemini-cli-container","owner":"ophiosdev","description":"A containerized version of Google's Gemini CLI tool","archived":false,"fork":false,"pushed_at":"2025-08-08T22:34:55.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-08T23:34:22.727Z","etag":null,"topics":["gemini","gemini-ai","gemini-api","gemini-cli","google-ai"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ophiosdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-08T21:17:11.000Z","updated_at":"2025-08-08T22:42:28.000Z","dependencies_parsed_at":"2025-08-08T23:34:27.571Z","dependency_job_id":"5b735b7d-6d32-4827-879b-99f43b08349b","html_url":"https://github.com/ophiosdev/gemini-cli-container","commit_stats":null,"previous_names":["ophiosdev/gemini-cli-container"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ophiosdev/gemini-cli-container","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ophiosdev%2Fgemini-cli-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ophiosdev%2Fgemini-cli-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ophiosdev%2Fgemini-cli-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ophiosdev%2Fgemini-cli-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ophiosdev","download_url":"https://codeload.github.com/ophiosdev/gemini-cli-container/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ophiosdev%2Fgemini-cli-container/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269669920,"owners_count":24456767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gemini","gemini-ai","gemini-api","gemini-cli","google-ai"],"created_at":"2025-08-10T03:19:48.698Z","updated_at":"2025-08-10T03:19:49.971Z","avatar_url":"https://github.com/ophiosdev.png","language":"Shell","readme":"# Gemini CLI Container\u003c!-- omit from toc --\u003e\n\n- [Container Architecture](#container-architecture)\n- [Building the Container Image](#building-the-container-image)\n  - [Build Arguments](#build-arguments)\n- [Authentication Setup](#authentication-setup)\n  - [Initial Authentication](#initial-authentication)\n  - [Authentication Persistence](#authentication-persistence)\n  - [Verifying Authentication](#verifying-authentication)\n  - [Authentication via GEMINI\\_API\\_KEY](#authentication-via-gemini_api_key)\n    - [When to Use API Key Authentication](#when-to-use-api-key-authentication)\n    - [Obtaining a GEMINI\\_API\\_KEY](#obtaining-a-gemini_api_key)\n    - [Using API Key with the Container](#using-api-key-with-the-container)\n- [Working with Gemini CLI from the Container](#working-with-gemini-cli-from-the-container)\n  - [Basic Usage Pattern](#basic-usage-pattern)\n  - [Volume Mounts Explained](#volume-mounts-explained)\n  - [Working Directory Context](#working-directory-context)\n- [Usage Examples](#usage-examples)\n  - [Interactive Session](#interactive-session)\n  - [Single Command Execution](#single-command-execution)\n  - [Processing Files](#processing-files)\n  - [Shell Alias for Convenience](#shell-alias-for-convenience)\n- [File Permissions](#file-permissions)\n  - [Option 1: Build with Custom UID](#option-1-build-with-custom-uid)\n  - [Option 2: Fix Permissions After Creation](#option-2-fix-permissions-after-creation)\n- [Troubleshooting](#troubleshooting)\n  - [Authentication Issues](#authentication-issues)\n  - [File Access Issues](#file-access-issues)\n  - [Container Issues](#container-issues)\n\nA containerized version of Google's Gemini CLI tool. This container provides a rootless environment\nfor running Gemini CLI commands while maintaining persistent authentication and seamless file access.\n\n## Container Architecture\n\n- **Rootless execution**: Runs as user `gemini` (UID 1000) instead of root\n- **Minimal base**: Uses `node:22-slim` which provides a smaller attack surface\n\n## Building the Container Image\n\nTo build the container image from the provided Dockerfile:\n\n```bash\ndocker build -t gemini-cli:dev .\n```\n\n### Build Arguments\n\nThe Dockerfile supports customization through build arguments:\n\n```bash\ndocker build \\\n  --build-arg GEMINI_CLI_VERSION=0.1.17 \\\n  --build-arg USERNAME=gemini \\\n  --build-arg UID=1000 \\\n  --build-arg GID=1000 \\\n  -t gemini-cli:dev .\n```\n\n## Authentication Setup\n\nThe Gemini CLI requires authentication with Google's services. Authentication data is stored locally in your HOME directory for persistence across container runs.\n\n### Initial Authentication\n\n1. **Run the container with HOME directory mapping**:\n\n   ```bash\n   docker run -it -v $HOME:/home/gemini --rm gemini-cli:dev\n   ```\n\n1. **Follow the authentication prompts** that appear when the container starts. The CLI will guide you through the OAuth flow.\n\n1. **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.\n\n### Authentication Persistence\n\nThe authentication setup persists because:\n\n- The container maps your host `$HOME` to `/home/gemini` inside the container\n- Gemini CLI stores credentials in the user's home directory\n- Subsequent container runs will reuse the existing authentication\n\n### Verifying Authentication\n\nTo verify your authentication is working:\n\n```bash\ndocker run -it -v $HOME:/home/gemini --rm gemini-cli:dev --help\n```\n\nIf authentication is successful, you should see the Gemini CLI help without authentication prompts.\n\n### Authentication via GEMINI_API_KEY\n\nAs 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.\n\n#### When to Use API Key Authentication\n\n- **Automation and scripting**: When running Gemini CLI in automated environments\n- **CI/CD pipelines**: For continuous integration and deployment workflows\n- **Non-interactive environments**: Where OAuth browser flow is not available\n- **Simplified setup**: When you prefer a single environment variable over persistent credential storage\n\n#### Obtaining a GEMINI_API_KEY\n\n1. **Google AI Studio** (Recommended):\n   - Visit [Google AI Studio](https://aistudio.google.com/)\n   - Navigate to the API keys section\n   - Create a new API key for your project\n\n2. **Google Cloud Console**:\n   - Access the Google Cloud Console\n   - Enable the Gemini API for your project\n   - Create credentials and generate an API key\n\n#### Using API Key with the Container\n\nWhen 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:\n\n**Basic usage with API key**:\n\n```bash\ndocker run -it -v ${PWD}:/work -e GEMINI_API_KEY=your_actual_api_key --rm gemini-cli:dev\n```\n\n**Using environment file for API key**:\n\n```bash\n# Create a .env file with your API key\necho \"GEMINI_API_KEY=your_actual_api_key\" \u003e .env\n\n# Use the environment file with Docker\ndocker run -it -v ${PWD}:/work --env-file .env --rm gemini-cli:dev\n```\n\nNote 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.\n\n## Working with Gemini CLI from the Container\n\nFor practical usage, you'll want to access files from your current working directory. Use both volume mounts for full functionality:\n\n### Basic Usage Pattern\n\n```bash\ndocker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev [GEMINI_CLI_ARGS]\n```\n\n### Volume Mounts Explained\n\n- **`-v $HOME:/home/gemini`**: Maps your home directory for authentication persistence\n- **`-v ${PWD}:/work`**: Maps your current working directory to the container's working directory\n- **`--rm`**: Automatically removes the container after execution\n- **`-it`**: Provides interactive terminal access\n\n### Working Directory Context\n\nThe container sets `/work` as the working directory, which corresponds to your current directory (`${PWD}`) on the host system. This means:\n\n- Files in your current directory are accessible within the container\n- Output files created by Gemini CLI will appear in your current directory\n- Relative paths work as expected\n\n## Usage Examples\n\n### Interactive Session\n\nStart an interactive session to run multiple commands:\n\n```bash\ndocker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev\n```\n\n### Single Command Execution\n\nRun a single Gemini CLI command:\n\n```bash\ndocker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev generate \"Explain this code\" --file ./script.py\n```\n\n### Processing Files\n\nWork with files in your current directory:\n\n```bash\n# Analyze a document\ndocker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev analyze --file ./document.txt\n\n# Generate content and save to file\ndocker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev generate \"Create a summary\" --output ./summary.txt\n```\n\n### Shell Alias for Convenience\n\nCreate a shell alias for easier usage:\n\n```bash\n# Add to your ~/.bashrc or ~/.zshrc\nalias gemini='docker run -it -v $HOME:/home/gemini -v ${PWD}:/work --rm gemini-cli:dev'\n\n# Then use simply:\ngemini --help\ngemini generate \"Hello, world!\"\n```\n\n## File Permissions\n\nThe container runs as user `gemini` with UID 1000. If your host user has a different UID, you may encounter permission issues. To resolve this:\n\n### Option 1: Build with Custom UID\n\n```bash\ndocker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t gemini-cli:dev .\n```\n\n### Option 2: Fix Permissions After Creation\n\n```bash\n# If files are created with wrong permissions\nsudo chown -R $(id -u):$(id -g) ./output-files\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n**Problem**: Authentication prompts appear on every run\n**Solution**: Ensure `$HOME` is properly mapped and authentication completed successfully\n\n**Problem**: Permission denied accessing config files\n**Solution**: Check that `$HOME/.config` is writable by your user\n\n### File Access Issues\n\n**Problem**: Cannot access files in current directory\n**Solution**: Ensure you're using `-v ${PWD}:/work` volume mount\n\n**Problem**: Created files have wrong ownership\n**Solution**: Rebuild container with your UID/GID or fix permissions afterward\n\n### Container Issues\n\n**Problem**: Container fails to start\n**Solution**: Verify Docker is running and image was built successfully\n\n**Problem**: Command not found errors\n**Solution**: Ensure you're passing arguments after the image name\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fophiosdev%2Fgemini-cli-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fophiosdev%2Fgemini-cli-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fophiosdev%2Fgemini-cli-container/lists"}