From c89d4f9c6c9773ad28596738969dd211008decc7 Mon Sep 17 00:00:00 2001 From: Tommaso Sciortino Date: Fri, 27 Feb 2026 15:41:47 -0800 Subject: [PATCH] docs: add Windows PowerShell equivalents for environments and scripting (#20333) --- docs/cli/cli-reference.md | 24 ++--- docs/cli/custom-commands.md | 9 ++ docs/cli/enterprise.md | 19 ++++ docs/cli/sandbox.md | 44 +++++++- docs/cli/telemetry.md | 29 +++++ docs/cli/tutorials/automation.md | 106 ++++++++++++++++++- docs/cli/tutorials/mcp-setup.md | 8 ++ docs/cli/tutorials/skills-getting-started.md | 8 ++ docs/extensions/writing-extensions.md | 16 +++ docs/get-started/authentication.md | 91 +++++++++++++++- docs/get-started/installation.md | 2 +- docs/hooks/best-practices.md | 34 +++++- docs/hooks/writing-hooks.md | 24 +++++ docs/ide-integration/index.md | 8 ++ docs/reference/configuration.md | 23 ++-- docs/reference/policy-engine.md | 10 ++ docs/resources/faq.md | 8 ++ docs/resources/troubleshooting.md | 5 +- 18 files changed, 434 insertions(+), 34 deletions(-) diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md index f8ff24bed6..c1599df69e 100644 --- a/docs/cli/cli-reference.md +++ b/docs/cli/cli-reference.md @@ -5,18 +5,18 @@ and parameters. ## CLI commands -| Command | Description | Example | -| ---------------------------------- | ---------------------------------- | --------------------------------------------------- | -| `gemini` | Start interactive REPL | `gemini` | -| `gemini "query"` | Query non-interactively, then exit | `gemini "explain this project"` | -| `cat file \| gemini` | Process piped content | `cat logs.txt \| gemini` | -| `gemini -i "query"` | Execute and continue interactively | `gemini -i "What is the purpose of this project?"` | -| `gemini -r "latest"` | Continue most recent session | `gemini -r "latest"` | -| `gemini -r "latest" "query"` | Continue session with a new prompt | `gemini -r "latest" "Check for type errors"` | -| `gemini -r "" "query"` | Resume session by ID | `gemini -r "abc123" "Finish this PR"` | -| `gemini update` | Update to latest version | `gemini update` | -| `gemini extensions` | Manage extensions | See [Extensions Management](#extensions-management) | -| `gemini mcp` | Configure MCP servers | See [MCP Server Management](#mcp-server-management) | +| Command | Description | Example | +| ---------------------------------- | ---------------------------------- | ------------------------------------------------------------ | +| `gemini` | Start interactive REPL | `gemini` | +| `gemini "query"` | Query non-interactively, then exit | `gemini "explain this project"` | +| `cat file \| gemini` | Process piped content | `cat logs.txt \| gemini`
`Get-Content logs.txt \| gemini` | +| `gemini -i "query"` | Execute and continue interactively | `gemini -i "What is the purpose of this project?"` | +| `gemini -r "latest"` | Continue most recent session | `gemini -r "latest"` | +| `gemini -r "latest" "query"` | Continue session with a new prompt | `gemini -r "latest" "Check for type errors"` | +| `gemini -r "" "query"` | Resume session by ID | `gemini -r "abc123" "Finish this PR"` | +| `gemini update` | Update to latest version | `gemini update` | +| `gemini extensions` | Manage extensions | See [Extensions Management](#extensions-management) | +| `gemini mcp` | Configure MCP servers | See [MCP Server Management](#mcp-server-management) | ### Positional arguments diff --git a/docs/cli/custom-commands.md b/docs/cli/custom-commands.md index e84839b8a3..dd2698290e 100644 --- a/docs/cli/custom-commands.md +++ b/docs/cli/custom-commands.md @@ -278,11 +278,20 @@ Let's create a global command that asks the model to refactor a piece of code. First, ensure the user commands directory exists, then create a `refactor` subdirectory for organization and the final TOML file. +**macOS/Linux** + ```bash mkdir -p ~/.gemini/commands/refactor touch ~/.gemini/commands/refactor/pure.toml ``` +**Windows (PowerShell)** + +```powershell +New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\commands\refactor" +New-Item -ItemType File -Force -Path "$env:USERPROFILE\.gemini\commands\refactor\pure.toml" +``` + **2. Add the content to the file:** Open `~/.gemini/commands/refactor/pure.toml` in your editor and add the diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index b6d469755b..44d8ba9467 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -203,6 +203,15 @@ with the actual Gemini CLI process, which inherits the environment variable. This makes it significantly more difficult for a user to bypass the enforced settings. +**PowerShell Profile (Windows alternative):** + +On Windows, administrators can achieve similar results by adding the environment +variable to the system-wide or user-specific PowerShell profile: + +```powershell +Add-Content -Path $PROFILE -Value '$env:GEMINI_CLI_SYSTEM_SETTINGS_PATH="C:\ProgramData\gemini-cli\settings.json"' +``` + ## User isolation in shared environments In shared compute environments (like ML experiment runners or shared build @@ -214,12 +223,22 @@ use the `GEMINI_CLI_HOME` environment variable to point to a unique directory for a specific user or job. The CLI will create a `.gemini` folder inside the specified path. +**macOS/Linux** + ```bash # Isolate state for a specific job export GEMINI_CLI_HOME="/tmp/gemini-job-123" gemini ``` +**Windows (PowerShell)** + +```powershell +# Isolate state for a specific job +$env:GEMINI_CLI_HOME="C:\temp\gemini-job-123" +gemini +``` + ## Restricting tool access You can significantly enhance security by controlling which tools the Gemini diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md index 392c71a176..1d075989af 100644 --- a/docs/cli/sandbox.md +++ b/docs/cli/sandbox.md @@ -55,12 +55,27 @@ from your organization's registry. ```bash # Enable sandboxing with command flag gemini -s -p "analyze the code structure" +``` -# Use environment variable +**Use environment variable** + +**macOS/Linux** + +```bash export GEMINI_SANDBOX=true gemini -p "run the test suite" +``` -# Configure in settings.json +**Windows (PowerShell)** + +```powershell +$env:GEMINI_SANDBOX="true" +gemini -p "run the test suite" +``` + +**Configure in settings.json** + +```json { "tools": { "sandbox": "docker" @@ -99,26 +114,51 @@ use cases. To disable SELinux labeling for volume mounts, you can set the following: +**macOS/Linux** + ```bash export SANDBOX_FLAGS="--security-opt label=disable" ``` +**Windows (PowerShell)** + +```powershell +$env:SANDBOX_FLAGS="--security-opt label=disable" +``` + Multiple flags can be provided as a space-separated string: +**macOS/Linux** + ```bash export SANDBOX_FLAGS="--flag1 --flag2=value" ``` +**Windows (PowerShell)** + +```powershell +$env:SANDBOX_FLAGS="--flag1 --flag2=value" +``` + ## Linux UID/GID handling The sandbox automatically handles user permissions on Linux. Override these permissions with: +**macOS/Linux** + ```bash export SANDBOX_SET_UID_GID=true # Force host UID/GID export SANDBOX_SET_UID_GID=false # Disable UID/GID mapping ``` +**Windows (PowerShell)** + +```powershell +$env:SANDBOX_SET_UID_GID="true" # Force host UID/GID +$env:SANDBOX_SET_UID_GID="false" # Disable UID/GID mapping +``` + ## Troubleshooting ### Common issues diff --git a/docs/cli/telemetry.md b/docs/cli/telemetry.md index 28eaed8bd5..c812d37965 100644 --- a/docs/cli/telemetry.md +++ b/docs/cli/telemetry.md @@ -103,23 +103,52 @@ Before using either method below, complete these steps: 1. Set your Google Cloud project ID: - For telemetry in a separate project from inference: + + **macOS/Linux** + ```bash export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id" ``` + + **Windows (PowerShell)** + + ```powershell + $env:OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id" + ``` + - For telemetry in the same project as inference: + + **macOS/Linux** + ```bash export GOOGLE_CLOUD_PROJECT="your-project-id" ``` + **Windows (PowerShell)** + + ```powershell + $env:GOOGLE_CLOUD_PROJECT="your-project-id" + ``` + 2. Authenticate with Google Cloud: - If using a user account: ```bash gcloud auth application-default login ``` - If using a service account: + + **macOS/Linux** + ```bash export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json" ``` + + **Windows (PowerShell)** + + ```powershell + $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account.json" + ``` + 3. Make sure your account or service account has these IAM roles: - Cloud Trace Agent - Monitoring Metric Writer diff --git a/docs/cli/tutorials/automation.md b/docs/cli/tutorials/automation.md index 11e489aff3..fb1d8d48d2 100644 --- a/docs/cli/tutorials/automation.md +++ b/docs/cli/tutorials/automation.md @@ -37,10 +37,18 @@ output. Pipe a file: +**macOS/Linux** + ```bash cat error.log | gemini "Explain why this failed" ``` +**Windows (PowerShell)** + +```powershell +Get-Content error.log | gemini "Explain why this failed" +``` + Pipe a command: ```bash @@ -57,7 +65,10 @@ results to a file. You have a folder of Python scripts and want to generate a `README.md` for each one. -1. Save the following code as `generate_docs.sh`: +1. Save the following code as `generate_docs.sh` (or `generate_docs.ps1` for + Windows): + + **macOS/Linux (`generate_docs.sh`)** ```bash #!/bin/bash @@ -72,13 +83,34 @@ one. done ``` + **Windows PowerShell (`generate_docs.ps1`)** + + ```powershell + # Loop through all Python files + Get-ChildItem -Filter *.py | ForEach-Object { + Write-Host "Generating docs for $($_.Name)..." + + $newName = $_.Name -replace '\.py$', '.md' + # Ask Gemini CLI to generate the documentation and print it to stdout + gemini "Generate a Markdown documentation summary for @$($_.Name). Print the result to standard output." | Out-File -FilePath $newName -Encoding utf8 + } + ``` + 2. Make the script executable and run it in your directory: + **macOS/Linux** + ```bash chmod +x generate_docs.sh ./generate_docs.sh ``` + **Windows (PowerShell)** + + ```powershell + .\generate_docs.ps1 + ``` + This creates a corresponding Markdown file for every Python file in the folder. @@ -90,7 +122,10 @@ like `jq`. To get pure JSON data from the model, combine the ### Scenario: Extract and return structured data -1. Save the following script as `generate_json.sh`: +1. Save the following script as `generate_json.sh` (or `generate_json.ps1` for + Windows): + + **macOS/Linux (`generate_json.sh`)** ```bash #!/bin/bash @@ -105,13 +140,35 @@ like `jq`. To get pure JSON data from the model, combine the gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json ``` -2. Run `generate_json.sh`: + **Windows PowerShell (`generate_json.ps1`)** + + ```powershell + # Ensure we are in a project root + if (-not (Test-Path "package.json")) { + Write-Error "Error: package.json not found." + exit 1 + } + + # Extract data (requires jq installed, or you can use ConvertFrom-Json) + $output = gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | ConvertFrom-Json + $output.response | Out-File -FilePath data.json -Encoding utf8 + ``` + +2. Run the script: + + **macOS/Linux** ```bash chmod +x generate_json.sh ./generate_json.sh ``` + **Windows (PowerShell)** + + ```powershell + .\generate_json.ps1 + ``` + 3. Check `data.json`. The file should look like this: ```json @@ -129,8 +186,10 @@ Use headless mode to perform custom, automated AI tasks. ### Scenario: Create a "Smart Commit" alias -You can add a function to your shell configuration (like `.zshrc` or `.bashrc`) -to create a `git commit` wrapper that writes the message for you. +You can add a function to your shell configuration to create a `git commit` +wrapper that writes the message for you. + +**macOS/Linux (Bash/Zsh)** 1. Open your `.zshrc` file (or `.bashrc` if you use Bash) in your preferred text editor. @@ -170,6 +229,43 @@ to create a `git commit` wrapper that writes the message for you. source ~/.zshrc ``` +**Windows (PowerShell)** + +1. Open your PowerShell profile in your preferred text editor. + + ```powershell + notepad $PROFILE + ``` + +2. Scroll to the very bottom of the file and paste this code: + + ```powershell + function gcommit { + # Get the diff of staged changes + $diff = git diff --staged + + if (-not $diff) { + Write-Host "No staged changes to commit." + return + } + + # Ask Gemini to write the message + Write-Host "Generating commit message..." + $msg = $diff | gemini "Write a concise Conventional Commit message for this diff. Output ONLY the message." + + # Commit with the generated message + git commit -m "$msg" + } + ``` + + Save your file and exit. + +3. Run this command to make the function available immediately: + + ```powershell + . $PROFILE + ``` + 4. Use your new command: ```bash diff --git a/docs/cli/tutorials/mcp-setup.md b/docs/cli/tutorials/mcp-setup.md index 48c94cd78d..03b6e56376 100644 --- a/docs/cli/tutorials/mcp-setup.md +++ b/docs/cli/tutorials/mcp-setup.md @@ -20,10 +20,18 @@ Most MCP servers require authentication. For GitHub, you need a PAT. **Read/Write** access to **Issues** and **Pull Requests**. 3. Store it in your environment: +**macOS/Linux** + ```bash export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..." ``` +**Windows (PowerShell)** + +```powershell +$env:GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..." +``` + ## How to configure Gemini CLI You tell Gemini about new servers by editing your `settings.json`. diff --git a/docs/cli/tutorials/skills-getting-started.md b/docs/cli/tutorials/skills-getting-started.md index 2614a679ef..ee59641d21 100644 --- a/docs/cli/tutorials/skills-getting-started.md +++ b/docs/cli/tutorials/skills-getting-started.md @@ -14,10 +14,18 @@ responding correctly. 1. Run the following command to create the folders: + **macOS/Linux** + ```bash mkdir -p .gemini/skills/api-auditor/scripts ``` + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path ".gemini\skills\api-auditor\scripts" + ``` + ### Create the definition 1. Create a file at `.gemini/skills/api-auditor/SKILL.md`. This tells the agent diff --git a/docs/extensions/writing-extensions.md b/docs/extensions/writing-extensions.md index 213d77542e..b22f69e672 100644 --- a/docs/extensions/writing-extensions.md +++ b/docs/extensions/writing-extensions.md @@ -189,10 +189,18 @@ Custom commands create shortcuts for complex prompts. 1. Create a `commands` directory and a subdirectory for your command group: + **macOS/Linux** + ```bash mkdir -p commands/fs ``` + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path "commands\fs" + ``` + 2. Create a file named `commands/fs/grep-code.toml`: ```toml @@ -252,10 +260,18 @@ Skills are activated only when needed, which saves context tokens. 1. Create a `skills` directory and a subdirectory for your skill: + **macOS/Linux** + ```bash mkdir -p skills/security-audit ``` + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path "skills\security-audit" + ``` + 2. Create a `skills/security-audit/SKILL.md` file: ```markdown diff --git a/docs/get-started/authentication.md b/docs/get-started/authentication.md index e8696137cf..61d4a5c040 100644 --- a/docs/get-started/authentication.md +++ b/docs/get-started/authentication.md @@ -78,11 +78,20 @@ To authenticate and use Gemini CLI with a Gemini API key: 2. Set the `GEMINI_API_KEY` environment variable to your key. For example: + **macOS/Linux** + ```bash # Replace YOUR_GEMINI_API_KEY with the key from AI Studio export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" ``` + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_GEMINI_API_KEY with the key from AI Studio + $env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY" + ``` + To make this setting persistent, see [Persisting Environment Variables](#persisting-vars). @@ -114,12 +123,22 @@ or the location where you want to run your jobs. For example: +**macOS/Linux** + ```bash # Replace with your project ID and desired location (e.g., us-central1) export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" ``` +**Windows (PowerShell)** + +```powershell +# Replace with your project ID and desired location (e.g., us-central1) +$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" +$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" +``` + To make any Vertex AI environment variable settings persistent, see [Persisting Environment Variables](#persisting-vars). @@ -130,9 +149,17 @@ Consider this authentication method if you have Google Cloud CLI installed. > **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you > must unset them to use ADC: > +> **macOS/Linux** +> > ```bash > unset GOOGLE_API_KEY GEMINI_API_KEY > ``` +> +> **Windows (PowerShell)** +> +> ```powershell +> Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore +> ``` 1. Verify you have a Google Cloud project and Vertex AI API is enabled. @@ -160,9 +187,17 @@ pipelines, or if your organization restricts user-based ADC or API key creation. > **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you > must unset them: > +> **macOS/Linux** +> > ```bash > unset GOOGLE_API_KEY GEMINI_API_KEY > ``` +> +> **Windows (PowerShell)** +> +> ```powershell +> Remove-Item Env:\GOOGLE_API_KEY, Env:\GEMINI_API_KEY -ErrorAction Ignore +> ``` 1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete) and download the provided JSON file. Assign the "Vertex AI User" role to the @@ -171,11 +206,20 @@ pipelines, or if your organization restricts user-based ADC or API key creation. 2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON file's absolute path. For example: + **macOS/Linux** + ```bash # Replace /path/to/your/keyfile.json with the actual path export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" ``` + **Windows (PowerShell)** + + ```powershell + # Replace C:\path\to\your\keyfile.json with the actual path + $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\keyfile.json" + ``` + 3. [Configure your Google Cloud Project](#set-gcp). 4. Start the CLI: @@ -195,11 +239,20 @@ pipelines, or if your organization restricts user-based ADC or API key creation. 2. Set the `GOOGLE_API_KEY` environment variable: + **macOS/Linux** + ```bash # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" ``` + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key + $env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" + ``` + > **Note:** If you see errors like > `"API keys are not supported by this API..."`, your organization might > restrict API key usage for this service. Try the other Vertex AI @@ -243,11 +296,20 @@ To configure Gemini CLI to use a Google Cloud project, do the following: For example, to set the `GOOGLE_CLOUD_PROJECT_ID` variable: + **macOS/Linux** + ```bash # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" ``` + **Windows (PowerShell)** + + ```powershell + # Replace YOUR_PROJECT_ID with your actual Google Cloud project ID + $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" + ``` + To make this setting persistent, see [Persisting Environment Variables](#persisting-vars). @@ -257,16 +319,22 @@ To avoid setting environment variables for every terminal session, you can persist them with the following methods: 1. **Add your environment variables to your shell configuration file:** Append - the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`, - `~/.zshrc`, or `~/.profile`) and reload your shell (e.g., - `source ~/.bashrc`). + the environment variable commands to your shell's startup file. + + **macOS/Linux** (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.profile`): ```bash - # Example for .bashrc echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc source ~/.bashrc ``` + **Windows (PowerShell)** (e.g., `$PROFILE`): + + ```powershell + Add-Content -Path $PROFILE -Value '$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' + . $PROFILE + ``` + > **Warning:** Be aware that when you export API keys or service account > paths in your shell configuration file, any process launched from that > shell can read them. @@ -274,10 +342,13 @@ persist them with the following methods: 2. **Use a `.env` file:** Create a `.gemini/.env` file in your project directory or home directory. Gemini CLI automatically loads variables from the first `.env` file it finds, searching up from the current directory, - then in `~/.gemini/.env` or `~/.env`. `.gemini/.env` is recommended. + then in your home directory's `.gemini/.env` (e.g., `~/.gemini/.env` or + `%USERPROFILE%\.gemini\.env`). Example for user-wide settings: + **macOS/Linux** + ```bash mkdir -p ~/.gemini cat >> ~/.gemini/.env <<'EOF' @@ -286,6 +357,16 @@ persist them with the following methods: EOF ``` + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini" + @" + GOOGLE_CLOUD_PROJECT="your-project-id" + # Add other variables like GEMINI_API_KEY as needed + "@ | Out-File -FilePath "$env:USERPROFILE\.gemini\.env" -Encoding utf8 -Append + ``` + Variables are loaded from the first file found, not merged. ## Running in Google Cloud environments diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index c989642a12..c345584b69 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -13,7 +13,7 @@ installation methods, and release types. - "Casual" usage: 4GB+ RAM (short sessions, common tasks and edits) - "Power" usage: 16GB+ RAM (long sessions, large codebases, deep context) - **Runtime:** Node.js 20.0.0+ -- **Shell:** Bash or Zsh +- **Shell:** Bash, Zsh, or PowerShell - **Location:** [Gemini Code Assist supported locations](https://developers.google.com/gemini-code-assist/resources/available-locations#americas) - **Internet connection required** diff --git a/docs/hooks/best-practices.md b/docs/hooks/best-practices.md index fd80fc0b40..08dae0fdf8 100644 --- a/docs/hooks/best-practices.md +++ b/docs/hooks/best-practices.md @@ -167,6 +167,8 @@ try { Run hook scripts manually with sample JSON input to verify they behave as expected before hooking them up to the CLI. +**macOS/Linux** + ```bash # Create test input cat > test-input.json << 'EOF' @@ -187,7 +189,30 @@ cat test-input.json | .gemini/hooks/my-hook.sh # Check exit code echo "Exit code: $?" +``` +**Windows (PowerShell)** + +```powershell +# Create test input +@" +{ + "session_id": "test-123", + "cwd": "C:\\temp\\test", + "hook_event_name": "BeforeTool", + "tool_name": "write_file", + "tool_input": { + "file_path": "test.txt", + "content": "Test content" + } +} +"@ | Out-File -FilePath test-input.json -Encoding utf8 + +# Test the hook +Get-Content test-input.json | .\.gemini\hooks\my-hook.ps1 + +# Check exit code +Write-Host "Exit code: $LASTEXITCODE" ``` ### Check exit codes @@ -333,7 +358,7 @@ tool_name=$(echo "$input" | jq -r '.tool_name') ### Make scripts executable -Always make hook scripts executable: +Always make hook scripts executable on macOS/Linux: ```bash chmod +x .gemini/hooks/*.sh @@ -341,6 +366,10 @@ chmod +x .gemini/hooks/*.js ``` +**Windows Note**: On Windows, PowerShell scripts (`.ps1`) don't use `chmod`, but +you may need to ensure your execution policy allows them to run (e.g., +`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`). + ### Version control Commit hooks to share with your team: @@ -481,6 +510,9 @@ ls -la .gemini/hooks/my-hook.sh chmod +x .gemini/hooks/my-hook.sh ``` +**Windows Note**: On Windows, ensure your execution policy allows running +scripts (e.g., `Get-ExecutionPolicy`). + **Verify script path:** Ensure the path in `settings.json` resolves correctly. ```bash diff --git a/docs/hooks/writing-hooks.md b/docs/hooks/writing-hooks.md index 33357fccb2..ca40d1976c 100644 --- a/docs/hooks/writing-hooks.md +++ b/docs/hooks/writing-hooks.md @@ -28,6 +28,8 @@ Create a directory for hooks and a simple logging script. > This example uses `jq` to parse JSON. If you don't have it installed, you can > perform similar logic using Node.js or Python. +**macOS/Linux** + ```bash mkdir -p .gemini/hooks cat > .gemini/hooks/log-tools.sh << 'EOF' @@ -52,6 +54,28 @@ EOF chmod +x .gemini/hooks/log-tools.sh ``` +**Windows (PowerShell)** + +```powershell +New-Item -ItemType Directory -Force -Path ".gemini\hooks" +@" +# Read hook input from stdin +`$inputJson = `$input | Out-String | ConvertFrom-Json + +# Extract tool name +`$toolName = `$inputJson.tool_name + +# Log to stderr (visible in terminal if hook fails, or captured in logs) +[Console]::Error.WriteLine("Logging tool: `$toolName") + +# Log to file +"[`$(Get-Date -Format 'o')] Tool executed: `$toolName" | Out-File -FilePath ".gemini\tool-log.txt" -Append -Encoding utf8 + +# Return success with empty JSON +"{}" +"@ | Out-File -FilePath ".gemini\hooks\log-tools.ps1" -Encoding utf8 +``` + ## Exit Code Strategies There are two ways to control or block an action in Gemini CLI: diff --git a/docs/ide-integration/index.md b/docs/ide-integration/index.md index f16be2e730..6686421ca4 100644 --- a/docs/ide-integration/index.md +++ b/docs/ide-integration/index.md @@ -177,10 +177,18 @@ standalone terminal and want to manually associate it with a specific IDE instance, you can set the `GEMINI_CLI_IDE_PID` environment variable to the process ID (PID) of your IDE. +**macOS/Linux** + ```bash export GEMINI_CLI_IDE_PID=12345 ``` +**Windows (PowerShell)** + +```powershell +$env:GEMINI_CLI_IDE_PID=12345 +``` + When this variable is set, Gemini CLI will skip automatic detection and attempt to connect using the provided PID. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 6bfd69203b..a6c9ddccfd 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1332,7 +1332,8 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. - **`GEMINI_MODEL`**: - Specifies the default Gemini model to use. - Overrides the hardcoded default - - Example: `export GEMINI_MODEL="gemini-3-flash-preview"` + - Example: `export GEMINI_MODEL="gemini-3-flash-preview"` (Windows PowerShell: + `$env:GEMINI_MODEL="gemini-3-flash-preview"`) - **`GEMINI_CLI_IDE_PID`**: - Manually specifies the PID of the IDE process to use for integration. This is useful when running Gemini CLI in a standalone terminal while still @@ -1344,12 +1345,14 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. - By default, this is the user's system home directory. The CLI will create a `.gemini` folder inside this directory. - Useful for shared compute environments or keeping CLI state isolated. - - Example: `export GEMINI_CLI_HOME="/path/to/user/config"` + - Example: `export GEMINI_CLI_HOME="/path/to/user/config"` (Windows + PowerShell: `$env:GEMINI_CLI_HOME="C:\path\to\user\config"`) - **`GOOGLE_API_KEY`**: - Your Google Cloud API key. - Required for using Vertex AI in express mode. - Ensure you have the necessary permissions. - - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. + - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"` (Windows PowerShell: + `$env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`). - **`GOOGLE_CLOUD_PROJECT`**: - Your Google Cloud Project ID. - Required for using Code Assist or Vertex AI. @@ -1360,18 +1363,23 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. you have `GOOGLE_CLOUD_PROJECT` set in your global environment in Cloud Shell, it will be overridden by this default. To use a different project in Cloud Shell, you must define `GOOGLE_CLOUD_PROJECT` in a `.env` file. - - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. + - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` (Windows + PowerShell: `$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`). - **`GOOGLE_APPLICATION_CREDENTIALS`** (string): - **Description:** The path to your Google Application Credentials JSON file. - **Example:** `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` + (Windows PowerShell: + `$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\credentials.json"`) - **`GOOGLE_GENAI_API_VERSION`**: - Specifies the API version to use for Gemini API requests. - When set, overrides the default API version used by the SDK. - - Example: `export GOOGLE_GENAI_API_VERSION="v1"` + - Example: `export GOOGLE_GENAI_API_VERSION="v1"` (Windows PowerShell: + `$env:GOOGLE_GENAI_API_VERSION="v1"`) - **`OTLP_GOOGLE_CLOUD_PROJECT`**: - Your Google Cloud Project ID for Telemetry in Google Cloud - - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. + - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` (Windows + PowerShell: `$env:OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`). - **`GEMINI_TELEMETRY_ENABLED`**: - Set to `true` or `1` to enable telemetry. Any other value is treated as disabling it. @@ -1399,7 +1407,8 @@ the `advanced.excludedEnvVars` setting in your `settings.json` file. - **`GOOGLE_CLOUD_LOCATION`**: - Your Google Cloud Project Location (e.g., us-central1). - Required for using Vertex AI in non-express mode. - - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. + - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"` (Windows + PowerShell: `$env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`). - **`GEMINI_SANDBOX`**: - Alternative to the `sandbox` setting in `settings.json`. - Accepts `true`, `false`, `docker`, `podman`, or a custom command string. diff --git a/docs/reference/policy-engine.md b/docs/reference/policy-engine.md index 810c591c24..17d958acd0 100644 --- a/docs/reference/policy-engine.md +++ b/docs/reference/policy-engine.md @@ -10,9 +10,19 @@ confirmation. To create your first policy: 1. **Create the policy directory** if it doesn't exist: + + **macOS/Linux** + ```bash mkdir -p ~/.gemini/policies ``` + + **Windows (PowerShell)** + + ```powershell + New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.gemini\policies" + ``` + 2. **Create a new policy file** (e.g., `~/.gemini/policies/my-rules.toml`). You can use any filename ending in `.toml`; all such files in this directory will be loaded and combined: diff --git a/docs/resources/faq.md b/docs/resources/faq.md index 465ba40d2f..580d7875f3 100644 --- a/docs/resources/faq.md +++ b/docs/resources/faq.md @@ -88,10 +88,18 @@ You can configure your Google Cloud Project ID using an environment variable. Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell: +**macOS/Linux** + ```bash export GOOGLE_CLOUD_PROJECT="your-project-id" ``` +**Windows (PowerShell)** + +```powershell +$env:GOOGLE_CLOUD_PROJECT="your-project-id" +``` + To make this setting permanent, add this line to your shell's startup file (e.g., `~/.bashrc`, `~/.zshrc`). diff --git a/docs/resources/troubleshooting.md b/docs/resources/troubleshooting.md index 9e567652d9..ea6341a0d6 100644 --- a/docs/resources/troubleshooting.md +++ b/docs/resources/troubleshooting.md @@ -55,10 +55,13 @@ topics on: - Set the `NODE_USE_SYSTEM_CA=1` environment variable to tell Node.js to use the operating system's native certificate store (where corporate certificates are typically already installed). - - Example: `export NODE_USE_SYSTEM_CA=1` + - Example: `export NODE_USE_SYSTEM_CA=1` (Windows PowerShell: + `$env:NODE_USE_SYSTEM_CA=1`) - Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file. - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` + (Windows PowerShell: + `$env:NODE_EXTRA_CA_CERTS="C:\path\to\your\corporate-ca.crt"`) ## Common error messages and solutions