MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-30 21:52:50 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: document global cross-folder session resume

Browse Source
This commit is contained in:
Dmitry Lyalin
2026-03-22 17:56:59 -04:00
parent 6c119110e4
commit 81006a7f82
5 changed files with 75 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/cli-reference.md
+15 -15
View File
@@ -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 "<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 "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 "<session-id>" "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 <uuid>`) |
| `--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` |
docs/cli/session-management.md
+28 -17
View File
@@ -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/<project_hash>/chats/`,
where `<project_hash>` is a unique identifier based on your project's root
- **Location:** Sessions are stored under `~/.gemini/tmp/<project_hash>/chats/`,
where `<project_hash>` 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
docs/cli/tutorials/session-management.md
+16 -1
View File
@@ -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.
docs/reference/commands.md
+5 -1
View File
@@ -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.
docs/reference/configuration.md
+11 -4
View File
@@ -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 <identifier>`**:
- 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