docs(cli): document managed PowerShell completion setup - #1070
docs(cli): document managed PowerShell completion setup#1070HowardYan888 wants to merge 7 commits into
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughUpdates the CLI completion documentation with a manual-installation heading and separate Unix/macOS bash and Windows PowerShell examples. The uninstall section remains after the generate examples. ChangesCLI Documentation Reorganization
Estimated code review effort: 1 (Trivial) | ~3 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli.md`:
- Around line 1046-1047: The docs currently show a PowerShell snippet that uses
the overwrite redirect operator (`>`). Update the Windows (PowerShell) example
so it appends rather than overwrites: replace the line "openspec completion
generate powershell > $PROFILE" with a safe append variant — either "openspec
completion generate powershell >> $PROFILE" or the explicit PowerShell-safe form
"openspec completion generate powershell | Out-File -Append $PROFILE" and
optionally note how to edit the profile (e.g., notepad $PROFILE) so users can
inspect before modifying.
- Around line 1043-1044: The example uses a non-standard path
(~/.bash_completion.d/openspec) that isn't auto-sourced by bash on most systems;
update the docs for the "openspec completion generate bash" example to either
direct users to append to the common single-file location (~/.bash_completion)
or add a short note and the sourcing snippet that instructs users to source
~/.bash_completion.d/* from their ~/.bashrc/~/.bash_profile so the generated
file is actually loaded.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| # Unix/macOS (bash) | ||
| openspec completion generate bash > ~/.bash_completion.d/openspec |
There was a problem hiding this comment.
Verify the bash completion path works without additional setup.
The path ~/.bash_completion.d/openspec may not work automatically on most systems. The ~/.bash_completion.d/ directory is not typically auto-sourced by bash unless explicitly configured in ~/.bashrc or ~/.bash_profile.
Consider using ~/.bash_completion instead, or document that users must source the directory:
# Add to ~/.bashrc if using ~/.bash_completion.d/
for file in ~/.bash_completion.d/*; do
[ -r "$file" ] && source "$file"
doneAlternatively, update the example to append to the standard single-file location:
# Unix/macOS (bash)
openspec completion generate bash >> ~/.bash_completion🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/cli.md` around lines 1043 - 1044, The example uses a non-standard path
(~/.bash_completion.d/openspec) that isn't auto-sourced by bash on most systems;
update the docs for the "openspec completion generate bash" example to either
direct users to append to the common single-file location (~/.bash_completion)
or add a short note and the sourcing snippet that instructs users to source
~/.bash_completion.d/* from their ~/.bashrc/~/.bash_profile so the generated
file is actually loaded.
The shell completion documentation only showed Unix/bash examples, making it unusable for Windows users. Added platform-specific examples for both Unix/macOS (bash) and Windows (PowerShell). Changes: - Add Unix/macOS (bash) example with ~/.bash_completion.d path - Add Windows (PowerShell) example with C:\Users\y00031947\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 path - Improve clarity with platform labels Fixes: Windows users cannot use shell completion manual installation
Critical fix: Using '>' operator would overwrite the user's PowerShell profile, deleting existing configurations. Changed to '>>' to append instead of overwrite, preserving user's existing settings.
933e35b to
88f6ad1
Compare
clay-good
changed the title
2 participants
Status
LGTM for final review. Independent review found no blocking documentation issues. All GitHub checks passed on commit
2e10435ce; the PR is conflict-free and awaits human review. It has not been merged.What was wrong
The CLI reference lacked a PowerShell setup example. The original proposed
openspec completion generate powershell >> $PROFILEcould append with the wrong encoding, fail when the profile directory did not exist, duplicate the script on repeat runs, and leave a manual installation thatcompletion uninstallcannot remove.How it was fixed
$env:PROFILE = $PROFILEso OpenSpec targets the active host's profile, including redirected Documents paths.. $PROFILEto activate completions immediately and explain restarting after uninstall.Replication / proof
git diff --checkpassed.ZSH/ZSH_CUSTOMfrom the test process. The initial run's two completion-tip failures came from the developer's installed Oh My Zsh completions.archivetab completion, repeat installation without changing the profile, uninstall, and preservation of unrelated profile content and BOM. The uninstall check supplied--yesto answer the interactive confirmation.Notes / nits
Documentation-only; no release changeset needed. Windows PowerShell 5.1 was not executed locally. The existing installer shares a completion file between hosts in the same directory; configuring a second host when that file is already up to date is a separate pre-existing runtime limitation, not changed here.