tkmind/tkmind_go
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity

docs: session storage migration (#5682)

Browse Source
This commit is contained in:
dianed-square
2025-11-11 16:18:17 -08:00
committed by GitHub
parent 6f0fcd2306
commit 5648799482
6 changed files with 192 additions and 169 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/docs/guides/goose-cli-commands.md
+54 -59
View File
@@ -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:
- **`--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
@@ -35,7 +22,7 @@ goose --help
---
#### configure
Configure Goose settings - providers, extensions, etc.
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.
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.
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.
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
@@ -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
@@ -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"
@@ -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
- **`-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
```
---
@@ -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
- **`-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-.*"
@@ -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.
:::
---
@@ -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
- **`-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`
@@ -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)
@@ -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
# 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
- **`-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`). Used for legacy file-based session storage.
- **`--no-session`**: Run goose commands without creating or storing a session file
**Extension Options:**
@@ -301,7 +296,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
@@ -386,7 +381,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
@@ -396,19 +391,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
```
---
@@ -424,7 +419,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.
@@ -434,7 +429,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.
:::
---
@@ -468,11 +463,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
@@ -556,7 +551,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`
@@ -572,7 +567,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:**
@@ -606,10 +601,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