Changing Gemini CLI Directories: Workspace, Project Settings, and Global Config

When I need to change a Gemini CLI directory, I first separate three tasks: starting the agent in another repository, adding repositories to its workspace, and relocating its persistent configuration. Each uses a different mechanism.

Gemini CLI is Google’s open-source terminal agent. Alongside code inspection and assistance, it can execute shell commands with safeguards and integrate tools such as Google Search and Model Context Protocol (MCP) extensions. Those capabilities make directory scope matter: the files available to the agent and the location of its credentials are separate concerns.

Here’s how I approach each case, including the version-dependent parts I would check before relying on them.

Start with the directory you actually want to change

The default user configuration directory is .gemini under your home directory:

Scope	Typical location	Purpose
User, Linux/macOS	~/.gemini/	User settings and persistent state
User, Windows	%USERPROFILE%\.gemini	Windows user settings and persistent state
Project	.gemini/settings.json in the project	Project-specific settings
System	OS-specific locations, such as under /etc/ or %PROGRAMDATA%	System configuration, when applicable

Typical contents include settings.json, GEMINI.md, commands/, cached credentials, telemetry identifiers, and other local state. Project settings override corresponding user settings when operating in that project.

Historically, the user configuration path has been tied to the home directory and the .gemini name. I would therefore check the installed release before assuming a configuration-directory environment variable works.

For ordinary repository work, I start Gemini from the intended folder:

cd /path/to/your-project
gemini

That selects the starting working directory. It does not relocate the user configuration or credential cache.

Add another repository without moving configuration

If I only need the agent to inspect a second repository, workspace inclusion is the direct solution.

At startup:

gemini --include-directories /path/to/repo

Or inside an interactive session:

/directory add /path/to/another/project
/directory list

These commands extend the workspace context. They do not move ~/.gemini.

This is useful when a change spans an application and a shared library, or when another repository provides reference material. Moving configuration would not solve that access problem.

If a directory still appears unavailable, I check whether the CLI process can read it. Network mounts and filesystem permissions can prevent access even when the directory has been added successfully.

Don’t rely on shell-mode cd to switch the session

Some platforms have had issues where cd inside Gemini’s shell mode does not change the working directory as expected.

My practical workaround is to change directories in the parent terminal before launching the CLI. For additional context within an existing session, I use /directory add.

Keep repository settings with the repository

For project-specific behavior, I use a project .gemini directory instead of redirecting the global one:

your-project/
├── .gemini/
│   ├── settings.json
│   └── GEMINI.md
└── src/

Run gemini from the project directory so it can discover the project configuration and context. Context discovery can search upward through the directory tree.

This gives a repository its own settings while leaving user-wide state in the normal location. It also makes the intended scope easier to inspect: a repository override lives alongside the code it affects.

The distinction matters when debugging authentication. Adding project settings does not, by itself, move the user credential cache.

Relocate global configuration only when necessary

For a centralized configuration store, another drive, or a restricted home directory, there are two main options: a supported native override or a filesystem redirect.

Check environment-variable support for your release

Several similarly named settings serve different purposes:

• GEMINI_API_KEY supplies a key for Gemini API authentication.
• GEMINI_MODEL selects a model where supported.
• GEMINI_CLI_SYSTEM_SETTINGS_PATH overrides the system settings file path where supported.
• GEMINI_CONFIG_DIR has appeared as a code constant and in community proposals for a configurable directory.

A constant named GEMINI_CONFIG_DIR does not establish that the CLI reads an environment variable with that name. Support and behavior have varied, with Windows issues reported in particular.

If your installed version documents the directory override, the shell configuration looks like this:

export GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir"
gemini

PowerShell:

$env:GEMINI_CONFIG_DIR = 'C:\Users\you\CustomGemini'
gemini

Treat those as conditional examples. Before building CI around them, check the release documentation and verify where that version actually writes its state.

The system-settings override is narrower:

export GEMINI_CLI_SYSTEM_SETTINGS_PATH="/etc/my-gemini/system.settings.json"
gemini

Even when supported, that selects a system settings file; it is not a general relocation mechanism for credentials, commands, and caches.

Use a symlink or junction when native relocation is unavailable

A filesystem redirect lets the CLI continue addressing its expected path while the directory contents live elsewhere.

On Linux or macOS, assuming the current configuration exists and the destination parent is available:

# Preserve the current configuration.
mv "$HOME/.gemini" "$HOME/gemini_backup"

# Populate the destination before linking it.
mkdir -p /path/to/central/gemini-config
cp -a "$HOME/gemini_backup/." /path/to/central/gemini-config/

ln -s /path/to/central/gemini-config "$HOME/.gemini"

On Windows, a directory junction provides a similar approach. From an appropriately privileged PowerShell session:

Move-Item -Path "$env:USERPROFILE\.gemini" -Destination 'C:\GeminiConfigBackup'

New-Item -ItemType Directory -Path 'C:\CentralGeminiConfig' -Force
Copy-Item -Path 'C:\GeminiConfigBackup\*' -Destination 'C:\CentralGeminiConfig' -Recurse -Force

New-Item -ItemType Junction `
  -Path "$env:USERPROFILE\.gemini" `
  -Target 'C:\CentralGeminiConfig'

I keep the backup until the CLI has loaded the expected settings and authentication state.

Symlinks and junctions depend on filesystem privileges and can behave differently across Windows and container environments. Some CLI versions also restrict following certain symlinks for security, so I verify both settings.json and context discovery after the move.

Treat home-directory changes as an isolated-runtime option

In CI or containers, controlling the process’s effective home directory can influence where the default .gemini path resolves. The source environment may use HOME on Unix or profile-related values on Windows.

That change has a broader effect than a configuration override: other tools and authentication flows, including Google OAuth caches, may also depend on the home directory. I would reserve this approach for an isolated runtime whose filesystem and authentication setup I control.

Diagnose failures by scope

The error usually tells me which layer to inspect.

Symptom	What I check
Another repository is invisible	--include-directories, /directory add, and read permissions
Project settings seem ignored	Launch directory and project .gemini/settings.json
Relocated settings are missing	Link target, copied contents, and version-specific symlink behavior
GEMINI_CONFIG_DIR appears ignored	Whether that release supports it as an environment variable
Windows reports EPERM creating .gemini	Write permissions on %USERPROFILE%

For Windows EPERM, adjusting folder permissions or using an appropriately elevated terminal can resolve the underlying access problem. A supported alternate location or junction may also help when the default profile directory is unsuitable.

Keep API routing separate from directory configuration

Sometimes the underlying goal is to use Gemini from a script or CI job. In that case, a direct API request may be sufficient, without configuring the terminal agent.

A unified multi-model API such as CometAPI exposes an OpenAI-style chat-completions endpoint using bearer authentication:

export COMET_KEY="sk-xxxx"

curl -s -X POST "https://api.cometapi.com/v1/chat/completions" \
  -H "Authorization: Bearer $COMET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Summarize the 3 key benefits of unit tests."}
    ],
    "max_tokens": 300
  }' | jq .

This calls the model directly. It does not provide the CLI’s workspace, file inspection, or shell-tool behavior.

Connecting the official CLI to a gateway requires checking both custom-base-URL support and API compatibility. Some releases or proposals have introduced overrides such as GOOGLE_GEMINI_BASE_URL, but a base URL alone does not translate Gemini requests into OpenAI-style requests. A compatible endpoint or translating proxy is still necessary.

For model-ID mismatches, inspect the gateway’s /v1/models response and use the exact identifier. A variant such as gemini-2.5-flash-preview-04-17 should not be assumed interchangeable with a shorter family name.

For my own directory setup, I keep the choice narrow: project settings for repository behavior, workspace commands for additional files, and a verified relocation mechanism only when persistent state needs another home.

---

Originally published at cometapi.com