Standardize CLI argument flags and update documentation (#5516)

2025-11-06 18:10:44 -05:00
parent cc4d978c7b
commit 3bf769edfe
6 changed files with 158 additions and 92 deletions
@@ -7,6 +7,21 @@ 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.

+## 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

 #### help
@@ -79,8 +94,10 @@ goose update --reconfigure
 Start or resume interactive chat sessions.

 **Basic Options:**
+- **`--session-id <session_id>`**: Specify a session by its ID (e.g., '20250921_143022')
 - **`-n, --name <name>`**: Give the session a name
- **`-r, --resume`**: Resume a previous session  
+- **`-p, --path <path>`**: Legacy parameter for specifying session by file path
+- **`-r, --resume`**: Resume a previous session
 - **`--debug`**: Enable debug mode to output complete tool responses, detailed parameter values, and full file paths
 - **`--max-turns <NUMBER>`**: Set the maximum number of turns allowed without user input (default: 1000)

@@ -93,11 +110,12 @@ Start or resume interactive chat sessions.
 **Usage:**
 ```bash
 # Start a basic session
-goose session --name my-project
+goose session -n my-project

 # Resume a previous session
-goose session --resume --name my-project
-goose session --resume --id 2025250620_013617
+goose session --resume -n my-project
+goose session --resume --session-id 20250620_013617
+goose session --resume -p ./session.jsonl

 # Start with extensions
 goose session --with-extension "npx -y @modelcontextprotocol/server-memory"
@@ -112,7 +130,7 @@ goose session \
  --with-builtin "developer"

 # Control session behavior
-goose session --name my-session --debug --max-turns 25
+goose session -n my-session --debug --max-turns 25
 ```

 ---
@@ -146,14 +164,15 @@ goose session list --ascending
 Remove one or more saved sessions.

 **Options:**
- **`-i, --id <id>`**: Remove a specific session by its ID
+- **`--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

 **Usage:**
 ```bash
 # Remove a specific session by ID
-goose session remove -i 20250305_113223
+goose session remove --session-id 20250305_113223
+goose session remove --id 20250305_113223

 # Remove a specific session by its name
 goose session remove -n my-session
@@ -175,9 +194,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
+- **`--session-id <session_id>`**: Export a specific session by session ID
 - **`-n, --name <name>`**: Export a specific session by name
- **`-p, --path <path>`**: Export a specific session by file path
+- **`-p, --path <path>`**: Export a specific session by file path (legacy)
 - **`-o, --output <file>`**: Save exported content to a file (default: stdout)
 - **`--format <format>`**: Output format: `markdown`, `json`, `yaml`. Default is `markdown`

@@ -192,17 +211,17 @@ Export sessions in different formats for backup, sharing, migration, or document
 goose session export

 # Export specific session as JSON for backup
-goose session export --name my-session --format json --output session-backup.json
+goose session export -n my-session --format json -o session-backup.json

 # Export specific session as readable markdown
-goose session export --name my-session --output session.md
+goose session export -n my-session -o session.md

 # Export to stdout in different formats
-goose session export --id 20250305_113223 --format json
-goose session export --name my-session --format yaml
+goose session export --session-id 20250305_113223 --format json
+goose session export -n my-session --format yaml

-# Export session by path
-goose session export --path ./my-session.jsonl --output exported.md
+# Export session by path (legacy)
+goose session export -p ./my-session.jsonl -o exported.md
 ```

 ---
@@ -211,7 +230,7 @@ goose session export --path ./my-session.jsonl --output exported.md
 Generate a comprehensive diagnostics bundle for troubleshooting issues with a specific session.

 **Options:**
- **`-i, --id <id>`**: Generate diagnostics for a specific session by ID
+- **`--session-id <session_id>`**: Generate diagnostics for a specific session by ID
 - **`-n, --name <name>`**: Generate diagnostics for a specific session by name
 - **`-o, --output <file>`**: Save diagnostics bundle to a specific file path (default: `diagnostics_{session_id}.zip`)

@@ -224,13 +243,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 --id 20250305_113223
+goose session diagnostics --session-id 20250305_113223

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

 # Save diagnostics to a custom location
-goose session diagnostics --id 20250305_113223 --output /path/to/my-diagnostics.zip
+goose session diagnostics --session-id 20250305_113223 --output /path/to/my-diagnostics.zip

 # Interactive selection (prompts you to choose a session)
 goose session diagnostics
@@ -366,29 +385,29 @@ 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`)
+- `--schedule-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
- `--limit <NUMBER>`: Max number of sessions to display when using the `sessions` command
+- `-l, --limit <NUMBER>`: Max number of sessions to display when using the `sessions` command

 **Usage:**
 ```bash
 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
+goose schedule add --schedule-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 --limit 10
+goose schedule sessions --schedule-id daily-report -l 10

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

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

 ---
@@ -533,7 +533,7 @@ At the bottom of the `Schedule Details` page you can view the list of sessions c

  ```bash
  # 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
+  goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml
  ```
  You can use either a 5, 6, or 7-digit cron expression for full scheduling precision, following the format "seconds minutes hours day-of-month month day-of-week year".

@@ -39,13 +39,13 @@ The diagnostics feature creates a comprehensive troubleshooting bundle that incl

    ```sh
    # Generate diagnostics for a specific session
-    goose session diagnostics --id <session_id>
+    goose session diagnostics --session-id <session_id>

    # Interactive selection (prompts you to choose a session)
    goose session diagnostics

    # Save to a custom location
-    goose session diagnostics --id <session_id> --output /path/to/diagnostics.zip
+    goose session diagnostics --session-id <session_id> --output /path/to/diagnostics.zip
    ```

    To find your session ID, first list available sessions: