docs: session storage migration #5682
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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. | ||||||
|
|
||||||
|
|
||||||
|
Collaborator
There was a problem hiding this comment. some of these are still relevant right?
Contributor
There was a problem hiding this comment. @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. |
||||||
|
|
||||||
| ### Core Commands | ||||||
|
|
||||||
|
|
@@ -35,7 +22,7 @@ goose --help | |||||
| --- | ||||||
|
|
||||||
| #### configure | ||||||
| Configure goose settings - providers, extensions, etc. | ||||||
|
|
||||||
| **Usage:** | ||||||
| ```bash | ||||||
|
|
@@ -45,7 +32,7 @@ goose configure | |||||
| --- | ||||||
|
|
||||||
| #### info [options] | ||||||
| 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 | ||||||
|
|
@@ -58,7 +45,7 @@ goose info | |||||
| --- | ||||||
|
|
||||||
| #### version | ||||||
| Check the current goose version you have installed. | ||||||
|
|
||||||
| **Usage:** | ||||||
| ```bash | ||||||
|
|
@@ -68,11 +55,11 @@ goose --version | |||||
| --- | ||||||
|
|
||||||
| #### update [options] | ||||||
| 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 | ||||||
|
|
||||||
| **Usage:** | ||||||
| ```bash | ||||||
|
|
@@ -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., '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 | ||||||
|
|
@@ -114,8 +106,9 @@ goose session -n my-project | |||||
|
|
||||||
| # Resume a previous session | ||||||
| goose session --resume -n my-project | ||||||
| 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" | ||||||
|
|
@@ -139,23 +132,27 @@ goose session -n my-session --debug --max-turns 25 | |||||
| List all saved sessions. | ||||||
|
|
||||||
| **Options:** | ||||||
| - **`-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 | ||||||
|
There was a problem hiding this comment. Incorrect short flag ordering. According to the code in
Suggested change
Contributor
Author
There was a problem hiding this comment. The |
||||||
| - **`-l, --limit <number>`**: Limit the number of results | ||||||
|
|
||||||
| **Usage:** | ||||||
| ```bash | ||||||
| # List all sessions in text format (default) | ||||||
| goose session list | ||||||
|
|
||||||
| # 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 | ||||||
| ``` | ||||||
|
|
||||||
| --- | ||||||
|
|
@@ -164,18 +161,16 @@ goose session list --ascending | |||||
| Remove one or more saved sessions. | ||||||
|
|
||||||
| **Options:** | ||||||
| - **`-i, --id <ID>`**: Remove a specific session by its session ID | ||||||
|
There was a problem hiding this comment. Incorrect short flag. According to the code in |
||||||
| - **`-r, --regex <REGEX>`**: Remove sessions matching a regex pattern | ||||||
|
|
||||||
| **Usage:** | ||||||
| ```bash | ||||||
| # Interactive removal (prompts you to choose sessions) | ||||||
| goose session remove | ||||||
|
|
||||||
| # Remove a specific session by ID | ||||||
| goose session remove -i 20251108_3 | ||||||
|
|
||||||
| # Remove all sessions starting with "project-" | ||||||
| goose session remove -r "project-.*" | ||||||
|
|
@@ -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. | ||||||
| ::: | ||||||
|
|
||||||
| --- | ||||||
|
|
@@ -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:** | ||||||
| - **`-i, --id <ID>`**: Export a specific session by ID | ||||||
|
There was a problem hiding this comment. Incorrect short flag. According to the code in
Suggested change
|
||||||
| - **`-n, --name <name>`**: Export a specific session by name | ||||||
| - **`-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` | ||||||
|
|
||||||
|
|
@@ -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 -i 20251108_4 --format json | ||||||
| goose session export -n my-session --format yaml | ||||||
|
|
||||||
| # Export session by path (legacy) | ||||||
|
|
@@ -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 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 20251108_5 --output /path/to/my-diagnostics.zip | ||||||
|
Contributor
There was a problem hiding this comment. oh i didnt realize this part changes as well. thank you |
||||||
|
|
||||||
| # Interactive selection (prompts you to choose a session) | ||||||
| goose session diagnostics | ||||||
|
|
@@ -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 | ||||||
| - **`--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`). Used for legacy file-based session storage. | ||||||
|
There was a problem hiding this comment. Typo: "file- based" should be "file-based" (remove the space before the hyphen). |
||||||
| - **`--no-session`**: Run goose commands without creating or storing a session file | ||||||
|
|
||||||
| **Extension Options:** | ||||||
|
|
@@ -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 | ||||||
| goose run --recipe recipe.yaml | ||||||
|
|
||||||
| # Load a recipe and stay in an interactive session | ||||||
|
|
@@ -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:** | ||||||
| - `--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 | ||||||
|
|
@@ -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 --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 --id daily-report -l 10 | ||||||
|
|
||||||
| # Run a recipe immediately | ||||||
| goose schedule run-now --id daily-report | ||||||
|
|
||||||
| # Remove a scheduled job | ||||||
| goose schedule remove --id daily-report | ||||||
| ``` | ||||||
|
|
||||||
| --- | ||||||
|
|
@@ -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. | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
|
|
@@ -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. | ||||||
| ::: | ||||||
|
|
||||||
| --- | ||||||
|
|
@@ -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. | ||||||
|
|
||||||
| 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 | ||||||
|
|
@@ -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. | ||||||
|
|
||||||
| **Commands:** | ||||||
| - `/t` - Cycles through themes: `light` → `dark` → `ansi` → `light` | ||||||
|
|
@@ -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. | ||||||
| ::: | ||||||
|
|
||||||
| **Examples:** | ||||||
|
|
@@ -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. | ||||||
|
|
||||||
| **How it works:** | ||||||
| 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 | ||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The Chat Recall extension is listed under platform extensions that are "always available and enabled by default", but according to the code in
crates/goose/src/agents/extension.rs, Chat Recall hasdefault_enabled: false. Either move this to a separate section for "available but not enabled by default" extensions, or update the introductory text to clarify that not all listed platform extensions are enabled by default.