Standardize CLI argument flags and update documentation #5516

wpfleger96 · 2025-10-31T22:00:29Z

This PR establishes consistent flag naming patterns across all Goose CLI commands, eliminating confusion around --id vs --session-id, conflicting short flags, and mismatched documentation. Previously, session commands mixed --id and --session-id, the --name flag had a misleading id alias, and schedule commands lacked short flags entirely.

Before this change, users encountered inconsistent flag names across commands, making it unclear when to use --id versus --session-id. The Identifier struct's --name flag incorrectly aliased to id, and the -p short flag conflicted between path and working_dir usage. Schedule commands used generic --id, and documentation showed flags that didn't match the actual implementation.

Updated Identifier struct to use alias = "id" on --session-id (instead of on --name), removed -p short flag from legacy --path parameter, and kept -n for name
Changed SessionCommand::Remove to use --session-id and separate --name flag, updating handle_session_remove to accept three distinct parameters
Renamed all schedule command flags to --schedule-id keeping --id as a backwards compatible alias, updating handlers in schedule.rs
Fixed SessionCommand::List working_dir to use -w with -p as backward-compatible alias
Updated help strings to clarify "recurring scheduled job" for schedule-id and fixed session --resume help to reference --session-id instead of --path
Marked ServicesStatus and ServicesStop commands as [Deprecated]
Added "Flag Naming Conventions" section to documentation and updated all examples to reflect standardized patterns

Type of Change

github-actions · 2025-10-31T22:03:13Z

PR Preview Action v1.6.0
Preview removed because the pull request was closed.
2025-11-06 23:13 UTC

katzdave

Nice change! Let's get some more opinions from the team on this one since it's largely a matter of taste.

crates/goose-cli/src/cli.rs

Copilot

Pull Request Overview

This PR standardizes CLI flag naming conventions across the Goose CLI, making commands more intuitive and consistent. The changes focus on disambiguating session IDs from schedule IDs and establishing clear patterns for common flags.

Key changes:

Introduces explicit --session-id and --schedule-id flags to distinguish between session and schedule identifiers
Standardizes short flag conventions (-i for IDs, -n for names, -o for output, -l for limit, etc.)
Adds comprehensive flag naming documentation to help users understand the conventions
Updates all command handlers to use the new parameter names (session_id, schedule_id instead of generic id)

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
documentation/docs/guides/goose-cli-commands.md	Adds flag naming conventions section and updates all command examples to use the new standardized flags
crates/goose-cli/src/commands/session.rs	Updates session removal handler to support both `--session-id` and `--name` parameters with clearer error messages
crates/goose-cli/src/commands/schedule.rs	Renames all `id` parameters to `schedule_id` throughout schedule command handlers for clarity
crates/goose-cli/src/cli.rs	Updates CLI argument definitions to use new flag names, adds aliases for backward compatibility, and reorganizes flag shortcuts

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

crates/goose-cli/src/cli.rs

documentation/docs/guides/goose-cli-commands.md

dianed-square · 2025-11-06T20:35:05Z

Thanks @wpfleger96! Would you also be able to update the feature docs that reference the changed flags? Specifically:

guides/recipes/session-recipes.md): --id → --schedule-id
troubleshooting/diagnostics-and-reporting.md: --id → --session-id

It would be better to show the new canonical flag names even though the old flags still work via aliases.

* main: (60 commits) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615) Token state not showing on load, or after message is finished. (#5606) Change the other location too (#5608) feat(ui): bring back quick launcher (#5144) Support platform tools through CLI (#5570) Avoid web double write (#5601) fix: gemini flash -> pro for mcp smoke tests (#5574) Manual compaction test and fix (#5568) fix: tidy up claude cli handling (#5594) Remove jetbrains (#5602) feat(githubcopilot): add support for newer Copilot AI Models (#5603) fix: customised recipe to yaml string to avoid minininjia parsing error (#5494) Add pending extension indicator to extension panel (#5493) Add environment subsition for auth blocks (#5439) acp: ToolCallLocations and working cancellation (#5588) feat(providers): add Mistral AI provider (#5009) Listen for ctrl-c during provider request (#5585) Also accept null as description, not just missing (#5589) ...

Copilot

Pull Request Overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

crates/goose-cli/src/cli.rs

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

wpfleger96 · 2025-11-06T22:32:16Z

@dianed-square great catch thank you! just updated those feature docs and a couple more places I found while testing

* main: (31 commits) Standardize CLI argument flags and update documentation (#5516) Release 1.13.0 fix: move goosehints/AGENTS.md handling to goose, and out of developer extension (#5575) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615) Token state not showing on load, or after message is finished. (#5606) Change the other location too (#5608) feat(ui): bring back quick launcher (#5144) Support platform tools through CLI (#5570) Avoid web double write (#5601) fix: gemini flash -> pro for mcp smoke tests (#5574) Manual compaction test and fix (#5568) fix: tidy up claude cli handling (#5594) Remove jetbrains (#5602) feat(githubcopilot): add support for newer Copilot AI Models (#5603) fix: customised recipe to yaml string to avoid minininjia parsing error (#5494) Add pending extension indicator to extension panel (#5493) Add environment subsition for auth blocks (#5439) acp: ToolCallLocations and working cancellation (#5588) ...

…eanup * 'main' of github.com:block/goose: Standardize CLI argument flags and update documentation (#5516) Release 1.13.0 fix: move goosehints/AGENTS.md handling to goose, and out of developer extension (#5575) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615)

* main: (21 commits) differentiate debug/release in cache key (#5613) Unify subrecipe and subagent execution through shared recipe pipeline (#5082) Standardize CLI argument flags and update documentation (#5516) Release 1.13.0 fix: move goosehints/AGENTS.md handling to goose, and out of developer extension (#5575) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615) Token state not showing on load, or after message is finished. (#5606) Change the other location too (#5608) feat(ui): bring back quick launcher (#5144) Support platform tools through CLI (#5570) Avoid web double write (#5601) fix: gemini flash -> pro for mcp smoke tests (#5574) Manual compaction test and fix (#5568) fix: tidy up claude cli handling (#5594) Remove jetbrains (#5602) feat(githubcopilot): add support for newer Copilot AI Models (#5603) fix: customised recipe to yaml string to avoid minininjia parsing error (#5494) Add pending extension indicator to extension panel (#5493) ...

Signed-off-by: fbalicchia <[email protected]>

* origin/main: (34 commits) Remove some logging (#5631) Use session IDs as task IDs for subagents instead of UUIDs (#5398) Fix the naming (#5628) fix: default tetrate model is broken, replace with haiku-4.5 (#5535) (#5587) Fetch less and use the right SHA (#5621) feat(ui): add custom macOS dock menu with New Window option (#5099) feat: remove hints from recipe prompts (#5622) docs: October 2025 Community All-Stars spotlight, Hacktoberfest edition (#5625) differentiate debug/release in cache key (#5613) Unify subrecipe and subagent execution through shared recipe pipeline (#5082) Standardize CLI argument flags and update documentation (#5516) Release 1.13.0 fix: move goosehints/AGENTS.md handling to goose, and out of developer extension (#5575) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615) Token state not showing on load, or after message is finished. (#5606) Change the other location too (#5608) feat(ui): bring back quick launcher (#5144) Support platform tools through CLI (#5570) ...

* main: (33 commits) Fix Claude Code provider to default to Auto mode (#5638) (#5642) Scheduler cleanup (#5571) Better search paths and handling of CLI providers (#5554) docs: description required for "Add Extension" in cli - phase 2 (#5635) Remove some logging (#5631) Use session IDs as task IDs for subagents instead of UUIDs (#5398) Fix the naming (#5628) fix: default tetrate model is broken, replace with haiku-4.5 (#5535) (#5587) Fetch less and use the right SHA (#5621) feat(ui): add custom macOS dock menu with New Window option (#5099) feat: remove hints from recipe prompts (#5622) docs: October 2025 Community All-Stars spotlight, Hacktoberfest edition (#5625) differentiate debug/release in cache key (#5613) Unify subrecipe and subagent execution through shared recipe pipeline (#5082) Standardize CLI argument flags and update documentation (#5516) Release 1.13.0 fix: move goosehints/AGENTS.md handling to goose, and out of developer extension (#5575) fix: add standard context menu items to prevent empty right-click menu (#5616) Bump openapi in prepare-release (#5611) docs: add access control section to Developer tutorial (#5615) ...

Signed-off-by: Blair Allan <[email protected]>

Standardize CLI flags and update docs

9e6955e

katzdave reviewed Nov 5, 2025

View reviewed changes

crates/goose-cli/src/cli.rs Show resolved Hide resolved

crates/goose-cli/src/cli.rs Outdated Show resolved Hide resolved

crates/goose-cli/src/cli.rs Outdated Show resolved Hide resolved

crates/goose-cli/src/cli.rs Outdated Show resolved Hide resolved

Address PR feedback

4fbb701

wpfleger96 marked this pull request as ready for review November 5, 2025 21:39

wpfleger96 requested a review from a team as a code owner November 5, 2025 21:39

Copilot AI review requested due to automatic review settings November 5, 2025 21:39

Copilot AI reviewed Nov 5, 2025

View reviewed changes

crates/goose-cli/src/cli.rs Show resolved Hide resolved

crates/goose-cli/src/cli.rs Show resolved Hide resolved

documentation/docs/guides/goose-cli-commands.md Outdated Show resolved Hide resolved

copilot feedback

49fb505

DOsinga approved these changes Nov 6, 2025

View reviewed changes

update a few more docs

29f8054

Copilot AI review requested due to automatic review settings November 6, 2025 22:00

Copilot AI reviewed Nov 6, 2025

View reviewed changes

crates/goose-cli/src/cli.rs Show resolved Hide resolved

Copilot AI reviewed Nov 6, 2025

View reviewed changes

still a few more to standardize on Identifier

db2b04a

dianed-square approved these changes Nov 6, 2025

View reviewed changes

wpfleger96 merged commit 3bf769e into main Nov 6, 2025
19 of 21 checks passed

fbalicchia pushed a commit to fbalicchia/goose that referenced this pull request Nov 7, 2025

Standardize CLI argument flags and update documentation (block#5516)

22af881

Signed-off-by: fbalicchia <[email protected]>

github-actions bot mentioned this pull request Nov 11, 2025

chore(release): release version 1.14.0 (minor) #5676

Merged

This was referenced Nov 11, 2025

docs: session storage migration #5682

Merged

docs: update cli commands #5744

Merged

Surendhar-N-D pushed a commit to Surendhar-N-D/goose that referenced this pull request Nov 17, 2025

Standardize CLI argument flags and update documentation (block#5516)

dcafaeb

arul-cc pushed a commit to arul-cc/goose that referenced this pull request Nov 17, 2025

Standardize CLI argument flags and update documentation (block#5516)

7bb787d

BlairAllan pushed a commit to BlairAllan/goose that referenced this pull request Nov 29, 2025

Standardize CLI argument flags and update documentation (block#5516)

c7fe036

Signed-off-by: Blair Allan <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Standardize CLI argument flags and update documentation #5516

Standardize CLI argument flags and update documentation #5516

Uh oh!

wpfleger96 commented Oct 31, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

katzdave left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dianed-square commented Nov 6, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

wpfleger96 commented Nov 6, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Standardize CLI argument flags and update documentation #5516

Standardize CLI argument flags and update documentation #5516

Uh oh!

Conversation

wpfleger96 commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Uh oh!

github-actions bot commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

katzdave left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dianed-square commented Nov 6, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

wpfleger96 commented Nov 6, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

wpfleger96 commented Oct 31, 2025 •

edited

Loading

github-actions bot commented Oct 31, 2025 •

edited

Loading