diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md new file mode 100644 index 0000000000..337867c5ed --- /dev/null +++ b/docs/cli/cli-reference.md @@ -0,0 +1,101 @@ +# CLI cheatsheet + +This page provides a reference for commonly used Gemini CLI commands, options, +and parameters. + +## CLI commands + +| Command | Description | Example | +| ---------------------------------- | ---------------------------------- | --------------------------------------------------- | +| `gemini` | Start interactive REPL | `gemini` | +| `gemini "query"` | Query non-interactively, then exit | `gemini "explain this project"` | +| `gemini -p "query"` | Query via SDK, then exit | `gemini -p "explain this function"` | +| `cat file \| gemini -p "query"` | Process piped content | `cat logs.txt \| gemini -p "explain"` | +| `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 + +| Argument | Type | Description | +| -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ | +| `query` | string (variadic) | Positional prompt. Defaults to one-shot mode. Use `-i/--prompt-interactive` to execute and continue interactively. | + +## CLI Options + +| Option | Alias | Type | Default | Description | +| -------------------------------- | ----- | ------- | --------- | ---------------------------------------------------------------------------------------------------------- | +| `--debug` | `-d` | boolean | `false` | Run in debug mode with verbose logging | +| `--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-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` | +| `--yolo` | `-y` | boolean | `false` | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead. | +| `--experimental-acp` | - | boolean | - | Start in ACP (Agent Code Pilot) mode. **Experimental feature.** | +| `--experimental-zed-integration` | - | boolean | - | Run in Zed editor integration mode. **Experimental feature.** | +| `--allowed-mcp-server-names` | - | array | - | Allowed MCP server names (comma-separated or multiple flags) | +| `--allowed-tools` | - | array | - | Tools that are allowed to run without confirmation (comma-separated or multiple flags) | +| `--extensions` | `-e` | array | - | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags) | +| `--list-extensions` | `-l` | boolean | - | List all available extensions and exit | +| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or index number (e.g. `--resume 5`) | +| `--list-sessions` | - | boolean | - | List available sessions for the current project and exit | +| `--delete-session` | - | string | - | Delete a session by index number (use `--list-sessions` to see available sessions) | +| `--include-directories` | - | array | - | Additional directories to include in the workspace (comma-separated or multiple flags) | +| `--screen-reader` | - | boolean | - | Enable screen reader mode for accessibility | +| `--output-format` | `-o` | string | `text` | The format of the CLI output. Choices: `text`, `json`, `stream-json` | + +## Model selection + +The `--model` (or `-m`) flag allows you to specify which Gemini model to use. +You can use either model aliases (user-friendly names) or concrete model names. + +### Model aliases + +These are convenient shortcuts that map to specific models: + +| Alias | Resolves To | Description | +| ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `auto` | `gemini-2.5-pro` or `gemini-3-pro-preview` | **Default.** Resolves to the preview model if preview features are enabled, otherwise resolves to the standard pro model. | +| `pro` | `gemini-2.5-pro` or `gemini-3-pro-preview` | For complex reasoning tasks. Uses preview model if enabled. | +| `flash` | `gemini-2.5-flash` | Fast, balanced model for most tasks. | +| `flash-lite` | `gemini-2.5-flash-lite` | Fastest model for simple tasks. | + +## Extensions management + +| Command | Description | Example | +| -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------ | +| `gemini extensions install ` | Install extension from Git URL or local path | `gemini extensions install https://github.com/user/my-extension` | +| `gemini extensions install --ref ` | Install from specific branch/tag/commit | `gemini extensions install https://github.com/user/my-extension --ref develop` | +| `gemini extensions install --auto-update` | Install with auto-update enabled | `gemini extensions install https://github.com/user/my-extension --auto-update` | +| `gemini extensions uninstall ` | Uninstall one or more extensions | `gemini extensions uninstall my-extension` | +| `gemini extensions list` | List all installed extensions | `gemini extensions list` | +| `gemini extensions update ` | Update a specific extension | `gemini extensions update my-extension` | +| `gemini extensions update --all` | Update all extensions | `gemini extensions update --all` | +| `gemini extensions enable ` | Enable an extension | `gemini extensions enable my-extension` | +| `gemini extensions disable ` | Disable an extension | `gemini extensions disable my-extension` | +| `gemini extensions link ` | Link local extension for development | `gemini extensions link /path/to/extension` | +| `gemini extensions new ` | Create new extension from template | `gemini extensions new ./my-extension` | +| `gemini extensions validate ` | Validate extension structure | `gemini extensions validate ./my-extension` | + +See [Extensions Documentation](../extensions/index.md) for more details. + +## MCP server management + +| Command | Description | Example | +| ------------------------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `gemini mcp add ` | Add stdio-based MCP server | `gemini mcp add github npx -y @modelcontextprotocol/server-github` | +| `gemini mcp add --transport http` | Add HTTP-based MCP server | `gemini mcp add api-server http://localhost:3000 --transport http` | +| `gemini mcp add --env KEY=value` | Add with environment variables | `gemini mcp add slack node server.js --env SLACK_TOKEN=xoxb-xxx` | +| `gemini mcp add --scope user` | Add with user scope | `gemini mcp add db node db-server.js --scope user` | +| `gemini mcp add --include-tools tool1,tool2` | Add with specific tools | `gemini mcp add github npx -y @modelcontextprotocol/server-github --include-tools list_repos,get_pr` | +| `gemini mcp remove ` | Remove an MCP server | `gemini mcp remove github` | +| `gemini mcp list` | List all configured MCP servers | `gemini mcp list` | + +See [MCP Server Integration](../tools/mcp-server.md) for more details. diff --git a/docs/sidebar.json b/docs/sidebar.json index b835d334ce..3847a82b80 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -7,7 +7,8 @@ { "label": "Installation", "slug": "docs/get-started/installation" }, { "label": "Authentication", "slug": "docs/get-started/authentication" }, { "label": "Examples", "slug": "docs/get-started/examples" }, - { "label": "Gemini 3 (preview)", "slug": "docs/get-started/gemini-3" } + { "label": "Gemini 3 (preview)", "slug": "docs/get-started/gemini-3" }, + { "label": "CLI Reference", "slug": "docs/cli/cli-reference" } ] }, {