To simplify the user experience and prevent startup failures, the Gemini CLI has introduced structured extension settings that eliminate the need for manual environment variable configuration. This update enables extensions to automatically prompt users for required details during installation and securely stores sensitive information, such as API keys, directly in the system keychain. Users can now easily manage and override these configurations globally or per project using the new Gemini extensions config command.
Overview
Google introduces extension settings for Gemini CLI, a structured configuration system that prompts users for required settings (API keys, URLs, project IDs) during extension installation. This eliminates manual environment variable configuration, stores sensitive values securely in the system keychain, and supports both global and workspace-scoped overrides via the new `gemini extensions config` command.
What You'll Learn
1
How to define structured settings in a Gemini CLI extension manifest using the settings array in gemini-extension.json
2
How to manage extension configuration after installation using the gemini extensions config command
3
How to use workspace-scoped overrides to maintain project-specific extension configurations
4
Why storing sensitive settings like API keys in the system keychain is preferable to plain text environment variables
5
How to debug extension configuration issues using gemini extensions list and /extensions list commands
Prerequisites & Requirements
- Gemini CLI v0.28.0 or later installed
- Basic understanding of environment variables and CLI tools
- Familiarity with JSON configuration files
- Understanding of MCP (Model Context Protocol) servers for extension development(optional)
Key Questions Answered
How do Gemini CLI extension settings work and what problem do they solve?
Extension settings provide a structured approach where extension authors define required configuration (API keys, URLs, project IDs) in a settings array within gemini-extension.json. When users install the extension, Gemini CLI automatically prompts them for each setting, stores sensitive values in the system keychain, and provides the values to the MCP server. This eliminates manual environment variable exports and ambiguous startup failures from missing configuration.
How to define settings in a Gemini CLI extension manifest file?
Add a settings array to your gemini-extension.json file where each setting object includes a name (user-friendly label), description (explanation of what the value is), envVar (the environment variable name it maps to), and optionally sensitive: true for secrets. When sensitive is set to true, the input is obfuscated during entry and stored securely in the system keychain rather than plain text.
How to update Gemini CLI extension configuration after installation?
Use the gemini extensions config command. To update all settings interactively, run `gemini extensions config <extension-name>`. To update a specific setting, run `gemini extensions config <extension-name> <env-var-name>`. For project-specific overrides, add the --scope workspace flag to save values in the current directory's configuration rather than globally.
How to debug Gemini CLI extension configuration issues?
Use `gemini extensions list` from the command line or `/extensions list` as a built-in command within Gemini CLI. Both output a summary of installed extensions including their version status, source repository, and all current configuration settings. Sensitive values like passwords are masked with asterisks. This helps identify typos in project IDs or missing API keys that prevent extensions from working.
What is the difference between global and workspace-scoped Gemini CLI extension settings?
Global settings apply across all projects and are the default storage scope. Workspace-scoped settings are saved in the current directory's configuration using the --scope workspace flag, allowing project-specific values like different database cluster IDs or project identifiers. Workspace settings override global settings, ensuring the right configuration is used in the right context without polluting global configuration.
How does Gemini CLI handle sensitive extension settings like API keys and passwords?
When an extension author marks a setting with "sensitive": true in the manifest, Gemini CLI automatically obfuscates the input during entry (showing asterisks instead of characters) and stores the value securely in the operating system's keychain rather than in plain text configuration files. When listing extensions, sensitive values are displayed as masked asterisks for security.
What version of Gemini CLI supports extension settings?
Extension settings and the gemini extensions config command are available starting from Gemini CLI v0.28.0 and later. You can update to the latest version by running `npm install -g @google/gemini-cli@latest`. The feature works with extensions that define a settings array in their gemini-extension.json manifest file.
Technologies & Tools
Some links below are affiliate links. We may earn a commission if you make a purchase.
CLI Tool
Gemini CLI
Google's AI-powered command-line interface that supports extensions via MCP servers
Protocol
Mcp
Model Context Protocol servers used by Gemini CLI extensions to provide tools and capabilities
Database
Alloydb
Google Cloud database service used as a practical example of an extension requiring structured settings
Data Format
JSON
Format for the gemini-extension.json manifest file where extension settings are defined
Package Manager
Npm
Used to install and update Gemini CLI globally via @google/gemini-cli package
Database
Bigquery
Referenced as one of the Data Cloud extensions supporting the new settings feature
Database
Cloud SQL
Referenced Data Cloud extension with MySQL, PostgreSQL, and SQL Server variants
Database
Firestore
Referenced as one of the Data Cloud extensions with native mode support
Database
Spanner
Referenced as one of the Data Cloud extensions supporting the new settings feature
Analytics
Looker
Referenced as one of the Data Cloud extensions supporting the new settings feature
Key Actionable Insights
1Always mark API keys, passwords, and tokens with "sensitive": true in your extension manifest. This ensures credentials are stored in the system keychain rather than plain text files, preventing accidental exposure through configuration file leaks or version control commits.This is especially important for extensions that connect to cloud services like databases (AlloyDB, Cloud SQL) or third-party APIs where credential exposure could lead to unauthorized access.
2Use workspace-scoped settings for project-specific identifiers like database cluster IDs, project IDs, and region configurations. This allows developers working across multiple projects to maintain separate configurations without global setting conflicts.Apply workspace scope via `gemini extensions config <name> <var> --scope workspace`. This is particularly relevant for GCP-based extensions where different projects may target different regions, clusters, or databases.
3Write clear, descriptive setting descriptions that tell users exactly where to find the required values. Instead of just 'API Key', include guidance like 'Find this in your GCP Console under IAM' to reduce user friction and support requests.Good descriptions reduce onboarding time and prevent configuration errors from users entering incorrect values. This best practice is especially useful for complex cloud service configurations with multiple required parameters.
4Use `gemini extensions list` or `/extensions list` as a first debugging step when an extension fails to function properly. These commands display all active settings with their current values, making it easy to spot typos or missing configuration.Configuration errors like a misspelled project ID or missing API key are common causes of extension failures. The list command provides a quick verification without needing to inspect individual config files.
5Keep setting names concise and user-friendly since they appear as terminal prompts during installation. Names like 'Project ID', 'Region', and 'API Key' are more effective than verbose or technical environment variable names.The name field is what users see during the interactive setup flow, while envVar is the technical mapping. Separating display names from environment variables lets you maintain clean UX while preserving backward compatibility with existing MCP server configurations.
Common Pitfalls
1
Manually exporting environment variables for extension configuration instead of using the structured settings system. This approach is brittle, error-prone, and can lead to ambiguous startup failures when variables are missing or incorrectly named.
The new extension settings system eliminates this by prompting users during installation and automatically providing values to the MCP server. Migrate existing extensions to use the settings array in gemini-extension.json.
2
Storing sensitive values like API keys and passwords in plain text configuration files rather than marking them with "sensitive": true in the extension manifest. This risks exposing credentials if config files are accidentally committed to version control or shared.
When sensitive is set to true, Gemini CLI automatically stores the value in the operating system's keychain and obfuscates input during entry, providing defense-in-depth for credential management.
3
Using global settings for project-specific configuration values like database cluster IDs or project identifiers. This causes configuration conflicts when switching between projects and can lead to accidentally connecting to the wrong database or cloud project.
Use the --scope workspace flag to save project-specific settings in the local directory configuration, ensuring each project uses its own correct configuration values.
4
Writing vague or missing descriptions for extension settings, forcing users to dig through README files or source code to understand what values are expected and where to find them.
Provide clear, specific descriptions that include where users can find the required values (e.g., 'Find this in your GCP Console under IAM'). This reduces support burden and configuration errors.
Related Concepts
Mcp (model Context Protocol)
CLI Extension Architecture
System Keychain Credential Storage
Environment Variable Management
Google Cloud Platform Project Configuration
Alloydb Database Connectivity
Extension Manifest Files
Scoped Configuration Management
AI Tool Extensibility