Skip to content

fix(docs): fix headless mode docs #21287

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
g-samroberts merged 5 commits into from
Mar 9, 2026
Merged

fix(docs): fix headless mode docs #21287

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b40df9f
refactor: Update CLI prompt argument parsing to use `-p` for non-inte…
ame2en Mar 5, 2026
9858717
docs: clarify that interactive mode is not default when input/output …
ame2en Mar 5, 2026
e36b8ce
Apply suggestion from @gemini-code-assist[bot]
g-samroberts Mar 6, 2026
e3103ef
Merge branch 'main' into fix/wrong-headless-mode-docs
ame2en Mar 7, 2026
8bde454
fix:fixed review comments
ame2en Mar 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/changelogs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -533,7 +533,7 @@ on GitHub.
[pr](https://github.com/google-gemini/gemini-cli/pull/11284) by
[@abhipatel12](https://github.com/abhipatel12))
- **Non-interactive MCP commands:** Users can now run MCP slash commands in
non-interactive mode `gemini "/some-mcp-prompt"`.
non-interactive mode `gemini -p "/some-mcp-prompt"`.
Comment thread
ame2en marked this conversation as resolved.
Outdated
([pr](https://github.com/google-gemini/gemini-cli/pull/10194) by
[@capachino](https://github.com/capachino))
- **Removal of deprecated flags:** We’ve finally removed a number of deprecated
Expand Down Expand Up @@ -658,7 +658,7 @@ on GitHub.
([pr](https://github.com/google-gemini/gemini-cli/pull/8570) by
[@scidomino](https://github.com/scidomino))
- **Custom commands in Headless Mode:** Run custom slash commands directly from
the command line in non-interactive mode: `gemini "/joke Chuck Norris"`
the command line in non-interactive mode: `gemini -p "/joke Chuck Norris"`
Comment thread
ame2en marked this conversation as resolved.
Outdated
([pr](https://github.com/google-gemini/gemini-cli/pull/8305) by
[@capachino](https://github.com/capachino))
- **Small features, polish, reliability & bug fixes:** A large amount of
Expand Down
28 changes: 15 additions & 13 deletions docs/cli/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,26 @@ 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`<br>`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 "<session-id>" "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 -p "query"` | Query non-interactively | `gemini -p "summarize README.md"` |
| `gemini "query"` | Query and continue interactively, then exit | `gemini "explain this project"` |
Comment thread
ame2en marked this conversation as resolved.
Outdated
| `cat file \| gemini` | Process piped content | `cat logs.txt \| gemini`<br>`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 "<session-id>" "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

| Argument | Type | Description |
| -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `query` | string (variadic) | Positional prompt. Defaults to one-shot mode. Use `-i/--prompt-interactive` to execute and continue interactively. |
| `query` | string (variadic) | Positional prompt. Defaults to interactive mode in a TTY. Use `-p/--prompt` for non-interactive execution. |
Comment thread
g-samroberts marked this conversation as resolved.
Outdated

## CLI Options

Expand All @@ -32,7 +34,7 @@ and parameters.
| `--version` | `-v` | - | - | Show CLI version number and exit |
| `--help` | `-h` | - | - | Show help information |
| `--model` | `-m` | string | `auto` | Model to use. See [Model Selection](#model-selection) for available values. |
| `--prompt` | `-p` | string | - | Prompt text. Appended to stdin input if provided. **Deprecated:** Use positional arguments instead. |
| `--prompt` | `-p` | string | - | Prompt text. Appended to stdin input if provided. Forces non-interactive mode. |
| `--prompt-interactive` | `-i` | string | - | Execute prompt and continue in interactive mode |
| `--sandbox` | `-s` | boolean | `false` | Run in a sandboxed environment for safer execution |
| `--approval-mode` | - | string | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo` |
Expand Down
2 changes: 1 addition & 1 deletion docs/cli/headless.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ structured text or JSON output without an interactive terminal UI.
## Technical reference

Headless mode is triggered when the CLI is run in a non-TTY environment or when
providing a query as a positional argument without the interactive flag.
providing a query with the `-p` (or `--prompt`) flag.

### Output formats

Expand Down
23 changes: 12 additions & 11 deletions docs/cli/tutorials/automation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,15 @@ Headless mode runs Gemini CLI once and exits. It's perfect for:

## How to use headless mode

Run Gemini CLI in headless mode by providing a prompt as a positional argument.
This bypasses the interactive chat interface and prints the response to standard
output (stdout).
Run Gemini CLI in headless mode by providing a prompt with the `-p` (or
`--prompt`) flag. This bypasses the interactive chat interface and prints the
response to standard output (stdout). Positional arguments without the flag
default to interactive mode, unless the input or output is piped or redirected.

Run a single command:

```bash
gemini "Write a poem about TypeScript"
gemini -p "Write a poem about TypeScript"
```

## How to pipe input to Gemini CLI
Expand All @@ -40,19 +41,19 @@ Pipe a file:
**macOS/Linux**

```bash
cat error.log | gemini "Explain why this failed"
cat error.log | gemini -p "Explain why this failed"
Comment thread
g-samroberts marked this conversation as resolved.
```

**Windows (PowerShell)**

```powershell
Get-Content error.log | gemini "Explain why this failed"
Get-Content error.log | gemini -p "Explain why this failed"
Comment thread
g-samroberts marked this conversation as resolved.
```

Pipe a command:

```bash
git diff | gemini "Write a commit message for these changes"
git diff | gemini -p "Write a commit message for these changes"
Comment thread
g-samroberts marked this conversation as resolved.
```

## Use Gemini CLI output in scripts
Expand All @@ -78,7 +79,7 @@ one.
echo "Generating docs for $file..."

# Ask Gemini CLI to generate the documentation and print it to stdout
gemini "Generate a Markdown documentation summary for @$file. Print the
gemini -p "Generate a Markdown documentation summary for @$file. Print the
result to standard output." > "${file%.py}.md"
Comment thread
g-samroberts marked this conversation as resolved.
done
```
Expand All @@ -92,7 +93,7 @@ one.

$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
gemini -p "Generate a Markdown documentation summary for @$($_.Name). Print the result to standard output." | Out-File -FilePath $newName -Encoding utf8
Comment thread
g-samroberts marked this conversation as resolved.
}
```

Expand Down Expand Up @@ -214,7 +215,7 @@ wrapper that writes the message for you.

# Ask Gemini to write the message
echo "Generating commit message..."
msg=$(echo "$diff" | gemini "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
msg=$(echo "$diff" | gemini -p "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
Comment thread
g-samroberts marked this conversation as resolved.

# Commit with the generated message
git commit -m "$msg"
Expand Down Expand Up @@ -251,7 +252,7 @@ wrapper that writes the message for you.

# 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."
$msg = $diff | gemini -p "Write a concise Conventional Commit message for this diff. Output ONLY the message."
Comment thread
g-samroberts marked this conversation as resolved.

# Commit with the generated message
git commit -m "$msg"
Expand Down