workflow: auto-update cli-commands on release by dianed-square · Pull Request #6755 · block/goose

dianed-square · 2026-01-27T22:16:02Z

Summary

Automates detection and documentation of CLI changes between releases.

Extracts CLI structure from tagged versions
Generates AI-powered change analysis
Updates goose-cli-commands.md automatically
Creates PRs with documentation changes

Type of Change

AI Assistance

This PR was created or reviewed with AI assistance

Testing

Tested across multiple version ranges locally and in my fork, e.g.:

v1.13.2 → v1.14.0 (12 commands modified, 11 breaking changes)
v1.17.0 → v1.20.1 (100% consistency across final 3 runs)

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1212274136275637

.github/workflows/docs-update-cli-ref.yml

github-actions · 2026-01-27T22:18:51Z

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-02-12 16:33 UTC

Copilot

Pull request overview

This PR automates the detection and documentation of CLI command changes between goose releases by building a comprehensive pipeline that:

Changes:

Adds scripts to extract CLI structure from goose binaries and compare versions
Implements AI-powered recipes to synthesize human-readable change documentation
Creates GitHub Actions workflow to automatically update CLI documentation on releases

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
`.github/workflows/docs-update-cli-ref.yml`	GitHub Actions workflow that triggers on release to compare CLI versions and create PRs
`documentation/automation/cli-command-tracking/scripts/run-pipeline.sh`	End-to-end orchestration script coordinating extraction, diffing, and AI synthesis
`documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh`	Downloads/builds goose binaries and extracts CLI structure via help output
`documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py`	Parses help text to generate structured JSON of commands and options
`documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py`	Compares two CLI structure JSONs and identifies breaking/non-breaking changes
`documentation/automation/cli-command-tracking/recipes/synthesize-cli-changes.yaml`	AI recipe to generate human-readable change documentation from diffs
`documentation/automation/cli-command-tracking/recipes/update-cli-commands.yaml`	AI recipe to apply changes to goose-cli-commands.md documentation
`documentation/automation/cli-command-tracking/config/skip-commands.json`	Configuration for commands to exclude from tracking
`documentation/automation/cli-command-tracking/README.md`	Comprehensive documentation of the automation system
`documentation/automation/cli-command-tracking/TESTING.md`	Detailed testing guide for local and CI workflows
`documentation/automation/cli-command-tracking/.gitignore`	Excludes generated output files from git

documentation/automation/cli-command-tracking/TESTING.md

Copilot · 2026-01-27T22:20:12Z

.github/workflows/docs-update-cli-ref.yml

+      - name: Configure goose for CI
+        env:
+          GOOSE_PROVIDER: ${{ vars.GOOSE_PROVIDER || 'openai' }}
+          GOOSE_MODEL: ${{ vars.GOOSE_MODEL || 'gpt-5' }}


The PR description mentions "GPT-5" which doesn't exist. This model name also appears in the workflow as the default (line 91). This will cause the workflow to fail. The description should be corrected to match whatever valid model is actually being used (likely gpt-4o or another existing model).

This workflow was tested in the fork (runs 21379191396, 21379197115, 21379200739) using provider: openai and model: gpt-5 with secrets.OPENAI_API_KEY, all runs succeeded. Will test in this repo after merging. We used the pattern from test-finder.yml but notice that hasn't been run for a while.

any reason not to use a claude model?

Maybe not a good reason. I found this pattern and was able to obtain an openai key for testing in my fork. I did see some Anthropic models used by other actions so I could try them.

Updated the workflow defaults to Anthropic (GOOSE_PROVIDER=anthropic, GOOSE_MODEL=claude-opus-4-5) and switched to ANTHROPIC_API_KEY, matching the patterns in .github/workflows/goose-pr-reviewer.yml and .github/workflows/goose-issue-solver.yml

documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh

Copilot · 2026-01-27T22:20:14Z

documentation/automation/cli-command-tracking/scripts/run-pipeline.sh

+        grep -v "^Closing session" | \
+        grep -v "^Loading recipe:" | \
+        grep -v "^Description:" | \
+        sed '/^$/N;/^\n$/D'


The sed command pattern /^$/N;/^\n$/D appears again with the same maintainability concerns as line 117.

Suggested change

sed '/^$/N;/^\n$/D'

awk 'NF { blank = 0 } !NF { blank++ } blank < 2'

replaced the sed '/^$/N;/^\n$/D' blank-line squashing with cat -s instead of the suggested awk one-liner
cat -s is simpler/readable and does the same “collapse consecutive blank lines” behavior on Ubuntu runners

documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py

documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py

Copilot · 2026-01-27T22:20:15Z

documentation/automation/cli-command-tracking/scripts/diff-cli-structures.py

+    try:
+        from datetime import timezone
+        now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+    except:


Except block directly handles BaseException.

Suggested change

except:

except Exception:

removed the try/except entirely and always use a timezone-aware UTC timestamp (datetime.now(timezone.utc)), since we already require Python 3.7+, which avoids the deprecated datetime.utcnow() fallback and eliminates the broad exception handler

Copilot · 2026-01-27T22:20:16Z

documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py

+    try:
+        from datetime import timezone
+        now = datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z')
+    except:


Except block directly handles BaseException.

Suggested change

except:

except (ImportError, AttributeError):

removed the try/except entirely and always use a timezone-aware UTC timestamp (datetime.now(timezone.utc)), since we already require Python 3.7+, which avoids the deprecated datetime.utcnow() fallback and eliminates the broad exception handler

Copilot

Pull request overview

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

documentation/automation/cli-command-tracking/TESTING.md

documentation/automation/cli-command-tracking/scripts/run-pipeline.sh

documentation/automation/cli-command-tracking/scripts/extract-cli-structure.sh

documentation/automation/cli-command-tracking/README.md

Copilot · 2026-02-11T20:39:00Z

documentation/automation/cli-command-tracking/scripts/run-pipeline.sh

+# - If new_version not provided: uses the most recent release tag (or RELEASE_TAG env var)
+# - HEAD is only used when explicitly passed for testing unreleased changes
+
+set -e


set -e won’t fail the script if goose run ... | sed | grep ... fails because the pipeline’s exit status is from the last command; add set -o pipefail (or set -euo pipefail) near the top so failed extraction/synthesis doesn’t silently produce empty/partial outputs.

Suggested change

set -e

set -e -o pipefail

Didn’t enable global set -o pipefail here because grep -v can exit 1 on empty output and would cause false failures. Instead we check PIPESTATUS[0] to ensure we still fail when goose run fails.

Copilot · 2026-02-11T20:39:00Z

documentation/automation/cli-command-tracking/scripts/extract-cli-structure.py

+    # First line has the flags and value_name
+    first_line = lines[0].strip()
+
+    # Extract short flag (e.g., -f)
+    short_match = re.search(r'-([a-zA-Z])\b', first_line)


parse_option_block() doesn’t capture help text that appears on the same line as the flags (common in clap output), so many options will end up with help: null and help-text diffs won’t be detected; parse the trailing description text from first_line.

Implemented inline option help capture by splitting the flags line on 2+ spaces (clap-style formatting), rather than a more complex parse.

.github/workflows/docs-update-cli-ref.yml

…provenance * origin/main: (68 commits) Upgraded npm packages for latest security updates (#7183) docs: reasoning effort levels for Codex provider (#6798) Fix speech local (#7181) chore: add .gooseignore to .gitignore (#6826) Improve error message logging from electron (#7130) chore(deps): bump jsonwebtoken from 9.3.1 to 10.3.0 (#6924) docs: standalone mcp apps and apps extension (#6791) workflow: auto-update cli-commands on release (#6755) feat(apps): Integrate AppRenderer from @mcp-ui/client SDK (#7013) fix(MCP): decode resource content (#7155) feat: reasoning_content in API for reasoning models (#6322) Fix/configure add provider custom headers (#7157) fix: handle keyring fallback as success (#7177) Update process-wrap to 9.0.3 (9.0.2 is yanked) (#7176) feat: support extra field in chatcompletion tool_calls for gemini openai compat (#6184) fix: replace panic with proper error handling in get_tokenizer (#7175) Lifei/smoke test for developer (#7174) fix text editor view broken (#7167) docs: White label guide (#6857) Add PATH detection back to developer extension (#7161) ... # Conflicts: # .github/workflows/nightly.yml

* origin/main: (21 commits) nit: show dir in title, and less... jank (#7138) feat(gemini-cli): use stream-json output and re-use session (#7118) chore(deps): bump qs from 6.14.1 to 6.14.2 in /documentation (#7191) Switch jsonwebtoken to use aws-lc-rs (already used by rustls) (#7189) chore(deps): bump qs from 6.14.1 to 6.14.2 in /evals/open-model-gym/mcp-harness (#7184) Add SLSA build provenance attestations to release workflows (#7097) fix save and run recipe not working (#7186) Upgraded npm packages for latest security updates (#7183) docs: reasoning effort levels for Codex provider (#6798) Fix speech local (#7181) chore: add .gooseignore to .gitignore (#6826) Improve error message logging from electron (#7130) chore(deps): bump jsonwebtoken from 9.3.1 to 10.3.0 (#6924) docs: standalone mcp apps and apps extension (#6791) workflow: auto-update cli-commands on release (#6755) feat(apps): Integrate AppRenderer from @mcp-ui/client SDK (#7013) fix(MCP): decode resource content (#7155) feat: reasoning_content in API for reasoning models (#6322) Fix/configure add provider custom headers (#7157) fix: handle keyring fallback as success (#7177) ...

workflow: auto-update cli-commands on release

f2b929e

dianed-square requested a review from a team as a code owner January 27, 2026 22:16

Copilot AI review requested due to automatic review settings January 27, 2026 22:16

Copilot started reviewing on behalf of dianed-square January 27, 2026 22:16 View session

github-advanced-security bot found potential problems Jan 27, 2026

View reviewed changes

.github/workflows/docs-update-cli-ref.yml Fixed Show fixed Hide fixed

Copilot AI reviewed Jan 27, 2026

View reviewed changes

chore: address Copilot and security feedback

ab34a6d

dianed-square enabled auto-merge February 10, 2026 22:48

chore: default CLI docs workflow to anthropic/claude

065a0a4

Copilot AI review requested due to automatic review settings February 11, 2026 20:33

Copilot started reviewing on behalf of dianed-square February 11, 2026 20:33 View session

Copilot AI reviewed Feb 11, 2026

View reviewed changes

chore: address additional Copilot feedback

ea48a81

blackgirlbytes approved these changes Feb 12, 2026

View reviewed changes

dianed-square added this pull request to the merge queue Feb 12, 2026

Merged via the queue into main with commit b904842 Feb 12, 2026
21 checks passed

dianed-square deleted the automation/cli-commands-doc branch February 12, 2026 16:29

github-actions bot mentioned this pull request Feb 12, 2026

chore(release): release version 1.24.0 (minor) #7102

Open

github-actions bot mentioned this pull request Feb 17, 2026

chore(release): release version 1.25.0 (minor) #7263

Open

	sed '/^$/N;/^\n$/D'
	awk 'NF { blank = 0 } !NF { blank++ } blank < 2'

Conversation

dianed-square commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

AI Assistance

Testing

Uh oh!

Uh oh!

github-actions bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dianed-square commented Jan 27, 2026 •

edited

Loading

github-actions bot commented Jan 27, 2026 •

edited

Loading