diff --git a/README.md b/README.md index f46c4569f09..3e6f56011ba 100644 --- a/README.md +++ b/README.md @@ -221,21 +221,21 @@ gemini -m gemini-2.5-flash Get a simple text response: ```bash -gemini -p "Explain the architecture of this codebase" +gemini "Explain the architecture of this codebase" ``` For more advanced scripting, including how to parse JSON and handle errors, use the `--output-format json` flag to get structured output: ```bash -gemini -p "Explain the architecture of this codebase" --output-format json +gemini "Explain the architecture of this codebase" --output-format json ``` For real-time event streaming (useful for monitoring long-running operations), use `--output-format stream-json` to get newline-delimited JSON events: ```bash -gemini -p "Run tests and deploy" --output-format stream-json +gemini "Run tests and deploy" --output-format stream-json ``` ### Quick Examples diff --git a/docs/cli/headless.md b/docs/cli/headless.md index 07e8254b548..c5d084e6bed 100644 --- a/docs/cli/headless.md +++ b/docs/cli/headless.md @@ -4,26 +4,26 @@ Headless mode allows you to run Gemini CLI programmatically from command line scripts and automation tools without any interactive UI. This is ideal for scripting, automation, CI/CD pipelines, and building AI-powered tools. -- [Headless Mode](#headless-mode) +- [Headless mode](#headless-mode) - [Overview](#overview) - - [Basic Usage](#basic-usage) - - [Direct Prompts](#direct-prompts) - - [Stdin Input](#stdin-input) - - [Combining with File Input](#combining-with-file-input) - - [Output Formats](#output-formats) - - [Text Output (Default)](#text-output-default) - - [JSON Output](#json-output) - - [Response Schema](#response-schema) - - [Example Usage](#example-usage) - - [Streaming JSON Output](#streaming-json-output) - - [When to Use Streaming JSON](#when-to-use-streaming-json) - - [Event Types](#event-types) - - [Basic Usage](#basic-usage) - - [Example Output](#example-output) - - [Processing Stream Events](#processing-stream-events) - - [Real-World Examples](#real-world-examples) - - [File Redirection](#file-redirection) - - [Configuration Options](#configuration-options) + - [Basic usage](#basic-usage) + - [Direct prompts](#direct-prompts) + - [Stdin input](#stdin-input) + - [Combining with file input](#combining-with-file-input) + - [Output formats](#output-formats) + - [Text output (default)](#text-output-default) + - [JSON output](#json-output) + - [Response schema](#response-schema) + - [Example usage](#example-usage) + - [Streaming JSON output](#streaming-json-output) + - [When to use streaming JSON](#when-to-use-streaming-json) + - [Event types](#event-types) + - [Basic usage](#basic-usage) + - [Example output](#example-output) + - [Processing stream events](#processing-stream-events) + - [Real-World examples](#real-world-examples) + - [File redirection](#file-redirection) + - [Configuration options](#configuration-options) - [Examples](#examples) - [Code review](#code-review) - [Generate commit messages](#generate-commit-messages) @@ -39,7 +39,7 @@ scripting, automation, CI/CD pipelines, and building AI-powered tools. The headless mode provides a headless interface to Gemini CLI that: -- Accepts prompts via command line arguments or stdin +- Accepts prompts as positional arguments, via stdin, or both combined - Returns structured output (text or JSON) - Supports file redirection and piping - Enables automation and scripting workflows @@ -49,10 +49,10 @@ The headless mode provides a headless interface to Gemini CLI that: ### Direct prompts -Use the `--prompt` (or `-p`) flag to run in headless mode: +Use a positional argument to run in headless mode: ```bash -gemini --prompt "What is machine learning?" +gemini "What is machine learning?" ``` ### Stdin input @@ -68,7 +68,7 @@ echo "Explain this code" | gemini Read from files and process with Gemini: ```bash -cat README.md | gemini --prompt "Summarize this documentation" +cat README.md | gemini "Summarize this documentation" ``` ## Output formats @@ -78,10 +78,10 @@ cat README.md | gemini --prompt "Summarize this documentation" Standard human-readable output: ```bash -gemini -p "What is the capital of France?" +gemini "What is the capital of France?" ``` -Response format: +Response: ``` The capital of France is Paris. @@ -143,7 +143,7 @@ The JSON output follows this high-level structure: #### Example usage ```bash -gemini -p "What is the capital of France?" --output-format json +gemini "What is the capital of France?" --output-format json ``` Response: @@ -252,13 +252,13 @@ The streaming format emits 6 event types: ```bash # Stream events to console -gemini --output-format stream-json --prompt "What is 2+2?" +gemini --output-format stream-json "What is 2+2?" # Save event stream to file -gemini --output-format stream-json --prompt "Analyze this code" > events.jsonl +gemini --output-format stream-json "Analyze this code" > events.jsonl # Parse with jq -gemini --output-format stream-json --prompt "List files" | jq -r '.type' +gemini --output-format stream-json "List files" | jq -r '.type' ``` #### Example output @@ -280,34 +280,33 @@ Save output to files or pipe to other commands: ```bash # Save to file -gemini -p "Explain Docker" > docker-explanation.txt -gemini -p "Explain Docker" --output-format json > docker-explanation.json +gemini "Explain Docker" > docker-explanation.txt +gemini "Explain Docker" --output-format json > docker-explanation.json # Append to file -gemini -p "Add more details" >> docker-explanation.txt +gemini "Add more details" >> docker-explanation.txt # Pipe to other tools -gemini -p "What is Kubernetes?" --output-format json | jq '.response' -gemini -p "Explain microservices" | wc -w -gemini -p "List programming languages" | grep -i "python" +gemini "What is Kubernetes?" --output-format json | jq '.response' +gemini "Explain microservices" | wc -w +gemini "List programming languages" | grep -i "python" ``` ## Configuration options Key command-line options for headless usage: -| Option | Description | Example | -| ----------------------- | ---------------------------------- | -------------------------------------------------- | -| `--prompt`, `-p` | Run in headless mode | `gemini -p "query"` | -| `--output-format` | Specify output format (text, json) | `gemini -p "query" --output-format json` | -| `--model`, `-m` | Specify the Gemini model | `gemini -p "query" -m gemini-2.5-flash` | -| `--debug`, `-d` | Enable debug mode | `gemini -p "query" --debug` | -| `--include-directories` | Include additional directories | `gemini -p "query" --include-directories src,docs` | -| `--yolo`, `-y` | Auto-approve all actions | `gemini -p "query" --yolo` | -| `--approval-mode` | Set approval mode | `gemini -p "query" --approval-mode auto_edit` | - -For complete details on all available configuration options, settings files, and -environment variables, see the +| Argument / Option | Effect | Example | +| ----------------------- | ---------------------------------------------- | ----------------------------------------------- | +| `[query]` | Run in headless mode | `gemini "query"` | +| `-o`, `--output-format` | Choose output format (text, json, stream-json) | `gemini "query" -o json` | +| `-m`, `--model` | Specify the Gemini model | `gemini "query" -m gemini-2.5-flash` | +| `-d`, `--debug` | Enable debug mode | `gemini "query" -d` | +| `-y`, `--yolo` | Auto-approve all actions | `gemini "query" -y` | +| `--approval-mode` | Set approval mode | `gemini "query" --approval-mode auto_edit` | +| `--include-directories` | Include additional directories | `gemini "query" --include-directories src,docs` | + +For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../get-started/configuration.md). ## Examples @@ -315,20 +314,20 @@ environment variables, see the #### Code review ```bash -cat src/auth.py | gemini -p "Review this authentication code for security issues" > security-review.txt +cat src/auth.py | gemini "Review this authentication code for security issues" > security-review.txt ``` #### Generate commit messages ```bash -result=$(git diff --cached | gemini -p "Write a concise commit message for these changes" --output-format json) +result=$(git diff --cached | gemini "Write a concise commit message for these changes" --output-format json) echo "$result" | jq -r '.response' ``` #### API documentation ```bash -result=$(cat api/routes.js | gemini -p "Generate OpenAPI spec for these routes" --output-format json) +result=$(cat api/routes.js | gemini "Generate OpenAPI spec for these routes" --output-format json) echo "$result" | jq -r '.response' > openapi.json ``` @@ -337,7 +336,7 @@ echo "$result" | jq -r '.response' > openapi.json ```bash for file in src/*.py; do echo "Analyzing $file..." - result=$(cat "$file" | gemini -p "Find potential bugs and suggest improvements" --output-format json) + result=$(cat "$file" | gemini "Find potential bugs and suggest improvements" --output-format json) echo "$result" | jq -r '.response' > "reports/$(basename "$file").analysis" echo "Completed analysis for $(basename "$file")" >> reports/progress.log done @@ -346,20 +345,20 @@ done #### Code review ```bash -result=$(git diff origin/main...HEAD | gemini -p "Review these changes for bugs, security issues, and code quality" --output-format json) +result=$(git diff origin/main...HEAD | gemini "Review these changes for bugs, security issues, and code quality" --output-format json) echo "$result" | jq -r '.response' > pr-review.json ``` #### Log analysis ```bash -grep "ERROR" /var/log/app.log | tail -20 | gemini -p "Analyze these errors and suggest root cause and fixes" > error-analysis.txt +grep "ERROR" /var/log/app.log | tail -20 | gemini "Analyze these errors and suggest root cause and fixes" > error-analysis.txt ``` #### Release notes generation ```bash -result=$(git log --oneline v1.0.0..HEAD | gemini -p "Generate release notes from these commits" --output-format json) +result=$(git log --oneline v1.0.0..HEAD | gemini "Generate release notes from these commits" --output-format json) response=$(echo "$result" | jq -r '.response') echo "$response" echo "$response" >> CHANGELOG.md @@ -368,7 +367,7 @@ echo "$response" >> CHANGELOG.md #### Model and tool usage tracking ```bash -result=$(gemini -p "Explain this database schema" --include-directories db --output-format json) +result=$(gemini "Explain this database schema" --include-directories db --output-format json) total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0') models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end') tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0') @@ -381,8 +380,7 @@ tail -5 usage.log ## Resources -- [CLI Configuration](../get-started/configuration.md) - Complete configuration - guide +- [CLI Configuration](../get-started/configuration.md) - Complete configuration guide - [Authentication](../get-started/authentication.md) - Setup authentication - [Commands](./commands.md) - Interactive commands reference - [Tutorials](./tutorials.md) - Step-by-step automation guides diff --git a/docs/cli/index.md b/docs/cli/index.md index 069c8024112..9d95cee07d5 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -53,10 +53,10 @@ The following example pipes a command to Gemini CLI from your terminal: echo "What is fine tuning?" | gemini ``` -You can also use the `--prompt` or `-p` flag: +You can also pass the prompt as a positional argument: ```bash -gemini -p "What is fine tuning?" +gemini "What is fine tuning?" ``` For comprehensive documentation on headless usage, scripting, automation, and diff --git a/docs/cli/sandbox.md b/docs/cli/sandbox.md index 09bb8f76d31..0969da766dc 100644 --- a/docs/cli/sandbox.md +++ b/docs/cli/sandbox.md @@ -54,11 +54,11 @@ from your organization's registry. ```bash # Enable sandboxing with command flag -gemini -s -p "analyze the code structure" +gemini -s "analyze the code structure" # Use environment variable export GEMINI_SANDBOX=true -gemini -p "run the test suite" +gemini "run the test suite" # Configure in settings.json { @@ -140,7 +140,7 @@ export SANDBOX_SET_UID_GID=false # Disable UID/GID mapping ### Debug mode ```bash -DEBUG=1 gemini -s -p "debug command" +DEBUG=1 gemini -s "debug command" ``` **Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect @@ -151,10 +151,10 @@ specific debug settings. ```bash # Check environment -gemini -s -p "run shell command: env | grep SANDBOX" +gemini -s "run shell command: env | grep SANDBOX" # List mounts -gemini -s -p "run shell command: mount | grep workspace" +gemini -s "run shell command: mount | grep workspace" ``` ## Security notes diff --git a/docs/get-started/configuration-v1.md b/docs/get-started/configuration-v1.md index e4a71a03e6f..c052e9f424b 100644 --- a/docs/get-started/configuration-v1.md +++ b/docs/get-started/configuration-v1.md @@ -647,9 +647,9 @@ for that specific session. - **`--model `** (**`-m `**): - Specifies the Gemini model to use for this session. - Example: `npm start -- --model gemini-1.5-pro-latest` -- **`--prompt `** (**`-p `**): - - Used to pass a prompt directly to the command. This invokes Gemini CLI in a - non-interactive mode. +- **`--prompt `** (**`-p `**) (Deprecated): + - This flag is deprecated. Use a positional argument to pass a prompt in non-interactive mode. + - Example: `gemini "your prompt here"` - **`--prompt-interactive `** (**`-i `**): - Starts an interactive session with the provided prompt as the initial input. - The prompt is processed within the interactive session, not before it. diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md index 810468e4064..8437a9df71e 100644 --- a/docs/get-started/configuration.md +++ b/docs/get-started/configuration.md @@ -1286,20 +1286,21 @@ You can customize this behavior in your `settings.json` file: Arguments passed directly when running the CLI can override other configurations for that specific session. -- **`--model `** (**`-m `**): - - Specifies the Gemini model to use for this session. - - Example: `npm start -- --model gemini-1.5-pro-latest` -- **`--prompt `** (**`-p `**): - - Used to pass a prompt directly to the command. This invokes Gemini CLI in a +- **`[query]`**: + - Positional argument. Used to pass a prompt directly to the command. This invokes Gemini CLI in a non-interactive mode. - For scripting examples, use the `--output-format json` flag to get structured output. + - Example: `gemini "Explain the architecture of this codebase"` +- **`--model `** (**`-m `**): + - Specifies the Gemini model to use for this session. + - Example: `npm start -- --model gemini-1.5-pro-latest` - **`--prompt-interactive `** (**`-i `**): - Starts an interactive session with the provided prompt as the initial input. - The prompt is processed within the interactive session, not before it. - Cannot be used when piping input from stdin. - - Example: `gemini -i "explain this code"` -- **`--output-format `**: + - Example: `gemini -i "Explain the architecture of this codebase"` +- **`--output-format `** (**`-o `**): - **Description:** Specifies the format of the CLI output for non-interactive mode. - **Values:** @@ -1313,7 +1314,7 @@ for that specific session. - **`--debug`** (**`-d`**): - Enables debug mode for this session, providing more verbose output. -- **`--help`** (or **`-h`**): +- **`--help`** (**`-h`**): - Displays help information about command-line arguments. - **`--yolo`**: - Enables YOLO mode, which automatically approves all tool calls. @@ -1323,7 +1324,7 @@ for that specific session. - `auto_edit`: Automatically approve edit tools (replace, write_file) while prompting for others - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`) - - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of + - Cannot be used together with `--yolo`. Use `--approval-mode yolo` instead of `--yolo` for the new unified approach. - Example: `gemini --approval-mode auto_edit` - **`--allowed-tools `**: diff --git a/docs/get-started/installation.md b/docs/get-started/installation.md index ef1d6b0ec83..259a39be6d0 100644 --- a/docs/get-started/installation.md +++ b/docs/get-started/installation.md @@ -53,7 +53,7 @@ the default way that the CLI executes tools that might have side effects. (using the standard installation described above), you can instruct it to run inside the sandbox container. ```bash - gemini --sandbox -y -p "your prompt here" + gemini --sandbox -y "your prompt here" ``` ### 3. Run from source (recommended for Gemini CLI contributors) diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts index 4d353b360c1..78e3be2e053 100755 --- a/packages/cli/src/config/config.ts +++ b/packages/cli/src/config/config.ts @@ -87,7 +87,7 @@ export async function parseArguments(settings: Settings): Promise { .locale('en') .scriptName('gemini') .usage( - 'Usage: gemini [options] [command]\n\nGemini CLI - Launch an interactive CLI, use -p/--prompt for non-interactive mode', + 'Usage: gemini [options] [query|command]\n\nGemini CLI - Launch an interactive CLI. Provide a query for non-interactive mode.', ) .option('debug', { @@ -270,7 +270,7 @@ export async function parseArguments(settings: Settings): Promise { return 'Cannot use both --prompt (-p) and --prompt-interactive (-i) together'; } if (argv['yolo'] && argv['approvalMode']) { - return 'Cannot use both --yolo (-y) and --approval-mode together. Use --approval-mode=yolo instead.'; + return 'Cannot use both --yolo (-y) and --approval-mode together. Use --approval-mode yolo instead.'; } if ( argv['outputFormat'] &&