MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-07-06 16:17:34 -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.