Skip to content

docs: session storage migration #5682

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dianed-square merged 5 commits into from
Nov 12, 2025
Merged

docs: session storage migration #5682

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
63112d6
session storage migration
dianed-square Nov 11, 2025
423233c
restore
dianed-square Nov 11, 2025
6474497
undo revert
dianed-square Nov 11, 2025
130e68c
mention chatrecall; clarify use case
dianed-square Nov 12, 2025
cecbdd7
typo
dianed-square Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 54 additions & 59 deletions documentation/docs/guides/goose-cli-commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,9 @@ sidebar_label: CLI Commands
toc_max_heading_level: 4
---

Goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. This guide covers all available CLI commands and interactive session features.
goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. This guide covers all available CLI commands and interactive session features.

## Flag Naming Conventions

Goose CLI follows consistent patterns for flag naming to make commands intuitive and predictable:
Copy link
Collaborator

@alexhancock alexhancock Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some of these are still relevant right?

Copy link
Contributor

@blackgirlbytes blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alexhancock correct us if we're wrong, but we believe these changes havent been released yet. our docs shouldnt be ahead of any features, so we're temporarily removing them and will restore once released.


- **`--session-id`**: Used for session identifiers (e.g., `20250305_113223`)
- **`--schedule-id`**: Used for schedule job identifiers (e.g., `daily-report`)
- **`-n, --name`**: Used for human-readable names
- **`-p, --path`**: Used for file paths (legacy support)
- **`-o, --output`**: Used for output file paths
- **`-r, --resume` or `-r, --regex`**: Context-dependent (resume for sessions, regex for filters)
- **`-v, --verbose`**: Used for verbose output
- **`-l, --limit`**: Used for limiting result counts
- **`-f, --format`**: Used for specifying output formats
- **`-w, --working-dir`**: Used for working directory filters

### Core Commands

Expand All @@ -35,7 +22,7 @@ goose --help
---

#### configure
Configure Goose settings - providers, extensions, etc.
Configure goose settings - providers, extensions, etc.

**Usage:**
```bash
Expand All @@ -45,7 +32,7 @@ goose configure
---

#### info [options]
Shows Goose information, including the version, configuration file location, session storage, and logs.
Shows goose information, including the version, configuration file location, session storage, and logs.

**Options:**
- **`-v, --verbose`**: Show detailed configuration settings, including environment variables and enabled extensions
Expand All @@ -58,7 +45,7 @@ goose info
---

#### version
Check the current Goose version you have installed.
Check the current goose version you have installed.

**Usage:**
```bash
Expand All @@ -68,11 +55,11 @@ goose --version
---

#### update [options]
Update the Goose CLI to a newer version.
Update the goose CLI to a newer version.

**Options:**
- **`--canary, -c`**: Update to the canary (development) version instead of the stable version
- **`--reconfigure, -r`**: Forces Goose to reset configuration settings during the update process
- **`--reconfigure, -r`**: Forces goose to reset configuration settings during the update process

**Usage:**
```bash
Expand All @@ -90,11 +77,16 @@ goose update --reconfigure

### Session Management

:::info Session Storage Migration
Starting with version 1.10.0, goose uses a SQLite database (`sessions.db`) instead of individual `.jsonl` files.
Your existing sessions are automatically imported to the database. Legacy `.jsonl` files remain on disk but are no longer managed by goose.
:::

#### session [options]
Start or resume interactive chat sessions.

**Basic Options:**
- **`--session-id <session_id>`**: Specify a session by its ID (e.g., '20250921_143022')
- **`--session-id <session_id>`**: Specify a session by its ID (e.g., '20251108_1')
- **`-n, --name <name>`**: Give the session a name
- **`-p, --path <path>`**: Legacy parameter for specifying session by file path
- **`-r, --resume`**: Resume a previous session
Expand All @@ -114,8 +106,9 @@ goose session -n my-project

# Resume a previous session
goose session --resume -n my-project
goose session --resume --session-id 20250620_013617
goose session --resume -p ./session.jsonl
goose session --resume --session-id 20251108_2
goose session --resume -p ./session.json # exported session
goose session --resume -p ./session.jsonl # legacy session storage

# Start with extensions
goose session --with-extension "npx -y @modelcontextprotocol/server-memory"
Expand All @@ -139,23 +132,27 @@ goose session -n my-session --debug --max-turns 25
List all saved sessions.

**Options:**
- **`-v, --verbose`**: Include session file paths in the output
- **`-f, --format <format>`**: Specify output format (`text` or `json`). Default is `text`
- **`--ascending`**: Sort sessions by date in ascending order (oldest first)
- **`-p, --working-dir <path>`**: Filter sessions by working directory
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect short flag ordering. According to the code in crates/goose-cli/src/cli.rs, the working_dir parameter has short = 'w' with short_alias = 'p'. The documentation should show the primary short form first: -w, --working-dir <path> (with -p as an alias if mentioned).

Suggested change
- **`-p, --working-dir <path>`**: Filter sessions by working directory
- **`-w, --working-dir <path>`**: Filter sessions by working directory

Copilot uses AI. Check for mistakes.
Copy link
Contributor Author

@dianed-square dianed-square Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The -w change isn't released yet, per --help
-p, --working_dir <WORKING_DIR>
Filter sessions by working directory

- **`-l, --limit <number>`**: Limit the number of results

**Usage:**
```bash
# List all sessions in text format (default)
goose session list

# List sessions with file paths
goose session list --verbose

# List sessions in JSON format
goose session list --format json

# Sort sessions by date in ascending order
goose session list --ascending

# Filter sessions by working directory
goose session list -p ~/projects/myapp

# List only the 10 most recent sessions
goose session list --limit 10
```

---
Expand All @@ -164,18 +161,16 @@ goose session list --ascending
Remove one or more saved sessions.

**Options:**
- **`--session-id <session_id>`**: Remove a specific session by its session ID
- **`-n, --name <name>`**: Remove a specific session by its name
- **`-r, --regex <pattern>`**: Remove sessions matching a regex pattern
- **`-i, --id <ID>`**: Remove a specific session by its session ID
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect short flag. According to the code in crates/goose-cli/src/cli.rs, the session_id argument has long = "session-id" with alias = "id", but no short form. This should be documented as --id <ID> or --session-id <ID> (without the -i short option).

Copilot uses AI. Check for mistakes.
- **`-r, --regex <REGEX>`**: Remove sessions matching a regex pattern

**Usage:**
```bash
# Remove a specific session by ID
goose session remove --session-id 20250305_113223
goose session remove --id 20250305_113223
# Interactive removal (prompts you to choose sessions)
goose session remove

# Remove a specific session by its name
goose session remove -n my-session
# Remove a specific session by ID
goose session remove -i 20251108_3

# Remove all sessions starting with "project-"
goose session remove -r "project-.*"
Expand All @@ -185,7 +180,7 @@ goose session remove -r ".*migration.*"
```

:::caution
Session removal is permanent and cannot be undone. Goose will show which sessions will be removed and ask for confirmation before deleting.
Session removal is permanent and cannot be undone. goose will show which sessions will be removed and ask for confirmation before deleting.
:::

---
Expand All @@ -194,9 +189,9 @@ Session removal is permanent and cannot be undone. Goose will show which session
Export sessions in different formats for backup, sharing, migration, or documentation purposes.

**Options:**
- **`--session-id <session_id>`**: Export a specific session by session ID
- **`-i, --id <ID>`**: Export a specific session by ID
Copy link

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect short flag. According to the code in crates/goose-cli/src/cli.rs, the session_id argument has long = "session-id" with alias = "id", but no short form. This should be documented as --id <ID> or --session-id <ID> (without the -i short option).

Suggested change
- **`-i, --id <ID>`**: Export a specific session by ID
- **`--id <ID>`**: Export a specific session by ID

Copilot uses AI. Check for mistakes.
- **`-n, --name <name>`**: Export a specific session by name
- **`-p, --path <path>`**: Export a specific session by file path (legacy)
- **`-p, --path <path>`**: Export a specific session by file path
- **`-o, --output <file>`**: Save exported content to a file (default: stdout)
- **`--format <format>`**: Output format: `markdown`, `json`, `yaml`. Default is `markdown`

Expand All @@ -217,7 +212,7 @@ goose session export -n my-session --format json -o session-backup.json
goose session export -n my-session -o session.md

# Export to stdout in different formats
goose session export --session-id 20250305_113223 --format json
goose session export -i 20251108_4 --format json
goose session export -n my-session --format yaml

# Export session by path (legacy)
Expand All @@ -243,13 +238,13 @@ Generate a comprehensive diagnostics bundle for troubleshooting issues with a sp
**Usage:**
```bash
# Generate diagnostics for a specific session by ID
goose session diagnostics --session-id 20250305_113223
goose session diagnostics --session-id 20251108_5

# Generate diagnostics for a session by name
goose session diagnostics --name my-project-session

# Save diagnostics to a custom location
goose session diagnostics --session-id 20250305_113223 --output /path/to/my-diagnostics.zip
goose session diagnostics --session-id 20251108_5 --output /path/to/my-diagnostics.zip
Copy link
Contributor

@blackgirlbytes blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh i didnt realize this part changes as well. thank you


# Interactive selection (prompts you to choose a session)
goose session diagnostics
Expand All @@ -272,14 +267,14 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/

**Input Options:**
- **`-i, --instructions <FILE>`**: Path to instruction file containing commands. Use `-` for stdin
- **`-t, --text <TEXT>`**: Input text to provide to Goose directly
- **`-t, --text <TEXT>`**: Input text to provide to goose directly
- **`--recipe <RECIPE_FILE_NAME> <OPTIONS>`**: Load a custom recipe in current session

**Session Options:**
- **`-s, --interactive`**: Continue in interactive mode after processing initial input
- **`-n, --name <name>`**: Name for this run session (e.g. `daily-tasks`)
- **`-r, --resume`**: Resume from a previous run
- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`)
- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl` for legacy session storage)
Copy link
Contributor

@blackgirlbytes blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wonder if this line could be confusing if you're not familiar with the legacy session storage. is it possible to run path for session for any other situation and do a diff example? or am i misunderstanding

Copy link
Contributor Author

@dianed-square dianed-square Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it's just for that. goose run --help says "Legacy parameter for backward compatibility. Extracts session ID from
the file path (e.g., '/path/to/20250325_200615.jsonl' -> '20250325_200615')."

I separated out the "Used for legacy file-based session storage" to hopefully make it easier to parse. The note in the Session Management section gives a bit more context.

- **`--no-session`**: Run goose commands without creating or storing a session file

**Extension Options:**
Expand All @@ -300,7 +295,7 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/
# Run from instruction file
goose run --instructions plan.md

# Load a recipe with a prompt that Goose executes and then exits
# Load a recipe with a prompt that goose executes and then exits
goose run --recipe recipe.yaml

# Load a recipe and stay in an interactive session
Expand Down Expand Up @@ -385,7 +380,7 @@ Automate recipes by running them on a [schedule](/docs/guides/recipes/session-re
- `run-now`: Run a scheduled recipe immediately

**Options:**
- `--schedule-id <NAME>`: A unique ID for the scheduled job (e.g. `daily-report`)
- `--id <NAME>`: A unique ID for the scheduled job (e.g. `daily-report`)
- `--cron "* * * * * *"`: Specifies when a job should run using a [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression)
- `--recipe-source <PATH>`: Path to the recipe YAML file
- `-l, --limit <NUMBER>`: Max number of sessions to display when using the `sessions` command
Expand All @@ -395,19 +390,19 @@ Automate recipes by running them on a [schedule](/docs/guides/recipes/session-re
goose schedule <COMMAND>

# Add a new scheduled recipe which runs every day at 9 AM
goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml
goose schedule add --id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml

# List all scheduled jobs
goose schedule list

# List the 10 most recent Goose sessions created by a scheduled job
goose schedule sessions --schedule-id daily-report -l 10
# List the 10 most recent goose sessions created by a scheduled job
goose schedule sessions --id daily-report -l 10

# Run a recipe immediately
goose schedule run-now --schedule-id daily-report
goose schedule run-now --id daily-report

# Remove a scheduled job
goose schedule remove --schedule-id daily-report
goose schedule remove --id daily-report
```

---
Expand All @@ -423,7 +418,7 @@ goose mcp <name>
---

#### acp
Run Goose as an Agent Client Protocol (ACP) agent server over stdio. This enables Goose to work with ACP-compatible clients like Zed.
Run goose as an Agent Client Protocol (ACP) agent server over stdio. This enables goose to work with ACP-compatible clients like Zed.

ACP is an emerging protocol specification that standardizes communication between AI agents and client applications, making it easier for clients to integrate with various AI agents.

Expand All @@ -433,7 +428,7 @@ goose acp
```

:::info
This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using Goose in ACP Clients](/docs/guides/acp-clients) for details.
This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using goose in ACP Clients](/docs/guides/acp-clients) for details.
:::

---
Expand Down Expand Up @@ -467,11 +462,11 @@ goose projects
### Interface

#### web
Start a new session in Goose Web, a lightweight web-based interface launched via the CLI that mirrors the desktop app's chat experience.
Start a new session in goose Web, a lightweight web-based interface launched via the CLI that mirrors the desktop app's chat experience.

Goose Web is particularly useful when:
- You want to access Goose with a graphical interface without installing the desktop app
- You need to use Goose from different devices, including mobile
goose Web is particularly useful when:
- You want to access goose with a graphical interface without installing the desktop app
- You need to use goose from different devices, including mobile
- You're working in an environment where installing desktop apps isn't practical

:::warning
Expand Down Expand Up @@ -555,7 +550,7 @@ Once you're in an interactive session (via `goose session` or `goose run --inter

### Themes

The `/t` command controls the syntax highlighting theme for markdown content in Goose CLI responses. This affects the styles used for headers, code blocks, bold/italic text, and other markdown elements in the response output.
The `/t` command controls the syntax highlighting theme for markdown content in goose CLI responses. This affects the styles used for headers, code blocks, bold/italic text, and other markdown elements in the response output.

**Commands:**
- `/t` - Cycles through themes: `light` → `dark` → `ansi` → `light`
Expand All @@ -571,7 +566,7 @@ The `/t` command controls the syntax highlighting theme for markdown content in
:::info
Syntax highlighting styles only affect the font, not the overall terminal interface. The `light` and `dark` themes have subtle differences in font color and weight.

The Goose CLI theme is independent from the Goose Desktop theme.
The goose CLI theme is independent from the goose Desktop theme.
:::

**Examples:**
Expand Down Expand Up @@ -605,10 +600,10 @@ goose session --name use-custom-theme

### Command History Search

The `Ctrl+R` shortcut provides interactive search through your stored CLI [command history](/docs/guides/logs#command-history). This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, Goose searches backwards through your history for matches.
The `Ctrl+R` shortcut provides interactive search through your stored CLI [command history](/docs/guides/logs#command-history). This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, goose searches backwards through your history for matches.

**How it works:**
1. Press `Ctrl+R` in your Goose CLI session
1. Press `Ctrl+R` in your goose CLI session
2. Type a search term
3. Navigate through the results using:
- `Ctrl+R` to cycle backwards through earlier matches
Expand Down
Loading