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

Description and use

Managing Gemini CLI directories: start from any repo, include other repos in the workspace, keep project settings in .gemini/, and relocate global config via env vars, symlinks, or junctions, preserving state and credentials.

Problem

Managing Gemini CLI directory scopes—user, project, and global—while ensuring correct configuration, credentials, and workspace inclusion.

Outcome

Gemini CLI can be run from any repository, include multiple repositories in its workspace, maintain per‑project settings, and relocate global configuration without losing state or credentials.

Workflow

• Start Gemini in desired repo: cd /path/to/project && gemini
• Add another repo to workspace: gemini --include-directories /path/to/other_repo or /directory add /path/to/other_repo
• Create a project .gemini/ directory with settings.json and GEMINI.md and run gemini from that folder
• Relocate global config: set GEMINI_CONFIG_DIR env var or create a symlink/junction to a new location
• Verify settings.json and context discovery after relocation
• Diagnose failures by checking include‑directories, project settings, and read permissions

Evidence

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

Source

If your installed version documents the directory override, the shell configuration looks like this: export GEMINI_CONFIG_DIR="$HOME/custom_gemini_dir" gemini

Source