diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md index f8ff24bed6..c4eecbd520 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` | +| `gemini -i "query"` | Execute and continue interactively | `gemini -i "What is the purpose of this project?"` | +| `gemini -r "latest"` | Continue the most recent session across all folders | `gemini -r "latest"` | +| `gemini -r "latest" "query"` | Continue a previous session with a new prompt | `gemini -r "latest" "Check for type errors"` | +| `gemini -r "" "query"` | Resume a specific session by UUID from any folder | `gemini -r "a1b2c3d4-e5f6-7890-abcd-ef1234567890" "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 @@ -43,9 +43,9 @@ and parameters. | `--allowed-tools` | - | array | - | **Deprecated.** Use the [Policy Engine](../reference/policy-engine.md) instead. 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) | +| `--resume` | `-r` | string | - | Resume a previous session globally. Use `"latest"`, an index number from `--list-sessions`, or a full UUID (for example `--resume 5` or `--resume `) | +| `--list-sessions` | - | boolean | - | List available sessions across all folders and exit | +| `--delete-session` | - | string | - | Delete a session globally by index number or UUID (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` | diff --git a/docs/cli/session-management.md b/docs/cli/session-management.md index a1453148ae..8e68014318 100644 --- a/docs/cli/session-management.md +++ b/docs/cli/session-management.md @@ -15,11 +15,12 @@ session. - All tool executions (inputs and outputs). - Token usage statistics (input, output, cached, etc.). - Assistant thoughts and reasoning summaries (when available). -- **Location:** Sessions are stored in `~/.gemini/tmp//chats/`, - where `` is a unique identifier based on your project's root +- **Location:** Sessions are stored under `~/.gemini/tmp//chats/`, + where `` is a unique identifier based on a project's root directory. -- **Scope:** Sessions are project-specific. Switching directories to a different - project switches to that project's session history. +- **Scope:** Session storage remains organized per project, but session + discovery is global. You can list, resume, and delete auto-saved sessions from + any folder by index or UUID. ## Resuming sessions @@ -38,20 +39,28 @@ sessions. gemini --resume ``` - This immediately loads the most recent session. + This immediately loads the most recent session across all folders. - **Resume by index:** List available sessions first (see - [Listing sessions](#listing-sessions)), then use the index number: + [Listing sessions](#listing-sessions)), then use the index number from the + global session list: ```bash gemini --resume 1 ``` -- **Resume by ID:** You can also provide the full session UUID: +- **Resume by ID:** You can also provide the full session UUID from any folder: ```bash gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` +If the current folder is different from the session's original folder: + +- **Interactive mode:** Gemini CLI shows the original folder, your current + folder, and asks whether you want to resume the session in the current folder. +- **Non-interactive mode:** Gemini CLI exits with guidance telling you to `cd` + to the original folder and rerun the resume command there. + ### From the interactive interface While the CLI is running, use the `/resume` slash command to open the **Session @@ -64,12 +73,13 @@ Browser**: The Session Browser provides an interactive interface where you can perform the following actions: -- **Browse:** Scroll through a list of your past sessions. +- **Browse:** Scroll through a list of your past sessions across all folders. - **Preview:** See details like the session date, message count, and the first - user prompt. + user prompt, plus the original folder path. - **Search:** Press `/` to enter search mode, then type to filter sessions by ID or content. -- **Select:** Press **Enter** to resume the selected session. +- **Select:** Press **Enter** to resume the selected session. If the session was + created in a different folder, Gemini CLI confirms before continuing there. - **Esc:** Press **Esc** to exit the Session Browser. ## Managing sessions @@ -79,8 +89,8 @@ space. ### Listing sessions -To see a list of all available sessions for the current project from the command -line, use the `--list-sessions` flag: +To see a list of all available sessions from the command line, use the +`--list-sessions` flag: ```bash gemini --list-sessions @@ -89,11 +99,11 @@ gemini --list-sessions Output example: ```text -Available sessions for this project (3): +Available sessions (3): - 1. Fix bug in auth (2 days ago) [a1b2c3d4] - 2. Refactor database schema (5 hours ago) [e5f67890] - 3. Update documentation (Just now) [abcd1234] + 1. Fix bug in auth (2 days ago) [a1b2c3d4-e5f6-7890-abcd-ef1234567890] @ /Users/alex/project-a + 2. Refactor database schema (5 hours ago) [e5f67890-1234-5678-9abc-def012345678] @ /Users/alex/project-b + 3. Update documentation (Just now) [abcd1234-5678-90ef-abcd-1234567890ef] @ /Users/alex/project-c ``` ### Deleting sessions @@ -101,7 +111,8 @@ Available sessions for this project (3): You can remove old or unwanted sessions to free up space or declutter your history. -**From the command line:** Use the `--delete-session` flag with an index or ID: +**From the command line:** Use the `--delete-session` flag with an index or UUID +from the global list: ```bash gemini --delete-session 2 diff --git a/docs/cli/tutorials/session-management.md b/docs/cli/tutorials/session-management.md index 7815aa94d6..5732fb1a58 100644 --- a/docs/cli/tutorials/session-management.md +++ b/docs/cli/tutorials/session-management.md @@ -26,6 +26,19 @@ gemini -r This restores your chat history and memory, so you can say "Continue with the next step" immediately. +### Scenario: Resume a session from another folder + +If you know the session UUID, you can resume it from any folder: + +```bash +gemini -r a1b2c3d4-e5f6-7890-abcd-ef1234567890 +``` + +If that session was created in a different folder, Gemini CLI shows the original +folder and asks whether you want to continue in the current one. If you say no, +the CLI exits so you can `cd` to the original folder and rerun the command +there. + ### Scenario: Browse past sessions If you want to find a specific conversation from yesterday, use the interactive @@ -33,11 +46,13 @@ browser. **Command:** `/resume` -This opens a searchable list of all your past sessions. You'll see: +This opens a searchable list of all your past sessions across all folders. +You'll see: - A timestamp (e.g., "2 hours ago"). - The first user message (helping you identify the topic). - The number of turns in the conversation. +- The original folder for each session. Select a session and press **Enter** to load it. diff --git a/docs/reference/commands.md b/docs/reference/commands.md index ceb064a9bf..41faf5cb64 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -320,8 +320,12 @@ Slash commands provide meta-level control over the CLI itself. - **Search:** Use `/` to search through conversation content across all sessions - **Session Browser:** Interactive interface showing all saved sessions with - timestamps, message counts, and first user message for context + timestamps, message counts, the first user message for context, and the + original folder path - **Sorting:** Sort sessions by date or message count +- **Cross-folder behavior:** `/resume` shows sessions across all folders. If you + choose a session that was created in a different folder, Gemini CLI shows the + original folder and asks whether you want to continue in the current folder. - **Note:** All conversations are automatically saved as you chat - no manual saving required. See [Session Management](../cli/session-management.md) for complete details. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 5337d973b8..62a8fb9651 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1519,18 +1519,25 @@ for that specific session. - Lists all available extensions and exits. - **`--resume [session_id]`** (**`-r [session_id]`**): - Resume a previous chat session. Use "latest" for the most recent session, - provide a session index number, or provide a full session UUID. + provide a session index number from `--list-sessions`, or provide a full + session UUID. - If no session_id is provided, defaults to "latest". + - Session discovery is global, so you can resume a session from any folder. + - If the current folder does not match the session's original folder, + interactive mode asks for confirmation before resuming there. In + non-interactive mode, the CLI exits with guidance to rerun from the original + folder instead. - Example: `gemini --resume 5` or `gemini --resume latest` or `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume` - See [Session Management](../cli/session-management.md) for more details. - **`--list-sessions`**: - - List all available chat sessions for the current project and exit. + - List all available chat sessions across all folders and exit. - Shows session indices, dates, message counts, and preview of first user - message. + message, along with each session's original folder path when available. - Example: `gemini --list-sessions` - **`--delete-session `**: - - Delete a specific chat session by its index number or full session UUID. + - Delete a specific chat session globally by its index number or full session + UUID. - Use `--list-sessions` first to see available sessions, their indices, and UUIDs. - Example: `gemini --delete-session 3` or