Gemini CLI Installation and Configuration

Gemini CLI is Google's open-source terminal agent. It supports Google sign-in, Gemini API keys, and Vertex AI. This guide also covers Ya Code's Gemini-native compatible endpoint.

I. Prerequisites

• Install Node.js 20 or later. macOS users installing the Homebrew formula do not need a separate global npm installation.
• For Google services, use a Google account, a Google AI Studio API key, or a Vertex AI project. For Ya Code, create an access key first.
• Confirm that node -v and npm -v work in your terminal.
• Requirements can change; consult the official Gemini CLI repository and installation guide.

II. Installation (macOS and Windows)

macOS

Install with npm:

npm install -g @google/gemini-cli
gemini --version

Alternatively, use the supported Homebrew formula:

brew install gemini-cli
gemini --version

You can also run it without a global installation:

npx @google/gemini-cli

Windows

Run the following in PowerShell or Windows Terminal:

npm install -g @google/gemini-cli
gemini --version

If PowerShell blocks the npm-generated script, run gemini.cmd or use a terminal permitted by your organization's policy. Do not loosen the machine-wide execution policy just to launch the CLI.

III. Configuration Directories (macOS and Windows)

macOS

• User settings: ~/.gemini/settings.json
• User environment file: ~/.gemini/.env
• Project settings: <project>/.gemini/settings.json
• Project environment file: <project>/.gemini/.env

Windows

• User settings: %USERPROFILE%\.gemini\settings.json
• User environment file: %USERPROFILE%\.gemini\.env
• Project settings: <project>\.gemini\settings.json
• Project environment file: <project>\.gemini\.env

Create the directories if needed. Settings use JSON, while environment files use KEY=VALUE entries. Scope and .env discovery can evolve between releases, so refer to the Gemini CLI configuration guide.

IV. Configuration Examples

To connect through Ya Code, add the following to either the user-level or project-level .gemini/.env file:

GEMINI_API_KEY=sk-your-yacode-key
GOOGLE_GEMINI_BASE_URL=https://yacode.xyz

settings.json controls interface and tool behavior. This credential-free example is intentionally minimal; use the current release's /settings screen and official configuration reference for supported fields:

{
  "general": {
    "vimMode": false
  }
}

Then launch Gemini CLI from the project directory:

gemini

V. Configuration Notes

• GEMINI_API_KEY selects API-key authentication. In this example it contains a Ya Code key, not a Google OAuth credential.
• GOOGLE_GEMINI_BASE_URL routes requests to Ya Code's Gemini-native compatible API. Ya Code currently uses https://yacode.xyz as the root URL.
• For Google's hosted service, leave the custom base URL unset. Run gemini and choose Google sign-in, a Gemini API key, or Vertex AI. See the Gemini CLI authentication guide for the variables required by each method.
• .env stores environment variables; settings.json stores JSON settings. Any project .env containing credentials must be ignored by Git.

VI. Important Notes

• sk-your-yacode-key is a placeholder. Never commit a real key or paste it into an issue report.
• Handling of custom base URLs, authentication variables, and the settings schema can change between Gemini CLI releases. After upgrading, record gemini --version and verify compatibility with a non-sensitive request.
• Ya Code must expose a Gemini-native endpoint and a compatible model. An OpenAI-compatible endpoint is not automatically interchangeable with the Gemini API. Use Ya Code's current model list when troubleshooting model or authentication errors.
• Gemini CLI can invoke shell and file tools. Review context files and confirmation policies before opening an untrusted project.