Skip to content

docs(readme): give Linux and macOS a real install command - #22

Merged
countzero merged 1 commit into
mainfrom
develop
Sep 21, 2026
Merged

countzero merged 1 commit into
mainfrom
develop

Conversation

@countzero

Copy link
Copy Markdown
Owner

Documentation only. switch_claude_account.ps1 is byte-identical to v4.2.0, so this deliberately carries no version bump, no changelog entry and no release: tagging it would publish a release asset identical to the one already there. That is a knowing deviation from "a pull request takes develop into main and carries a release".

The trigger was a colleague declining the tool with "I'm not wrestling with PowerShell just to monitor". Walking the install path he would have walked turned up a table that gave Windows a command and sent the other two platforms off to read Microsoft's docs, which is backwards: Windows is the one platform where pwsh often already exists.

What changed

  • Replaced the Linux and macOS doc links with commands: sudo snap install powershell --classic and brew install powershell. Both were verified against their own registry rather than from memory, at 7.6.5 from Canonical (verified publisher) and 7.6.6 from Homebrew, and both clear the #Requires -Version 7.4 floor.
  • Kept both Microsoft links as the authority behind the commands, and named the two caveats that actually bite: neither package is a Microsoft build, and the snap needs snapd, which Ubuntu ships and Fedora, Arch and RHEL do not.
  • Padded the table, which did not satisfy the repo's own cell-width rule before it was touched.
  • Gave the download a pasteable Invoke-WebRequest line beside the prose link.
  • Renamed Without alias to Run it without installing and moved it ahead of the step that edits your PowerShell profile, since running it untouched is what a reader wants first from a tool that manages OAuth credentials. It now states what the two suggested actions do: help returns before sca resolves or creates anything, and usage reads slots and queries Anthropic without billing or switching the active account. Both claims were checked against Invoke-Main rather than assumed.
  • Pointed at Execution policy (Windows) from the first-run step instead of leaving it only at the far end of Platform Notes. The section itself did not move, because docs/architecture.md names that heading as its owner.
  • Switched both invocation examples from .\ to ./, which pwsh accepts on all three platforms.

Shortcomings

  • Neither new command was executed. I verified that both packages exist, are current, are actively maintained and ship above the 7.4 floor, but I am on Windows and never ran them. The residual risk is that one fails for a reason a registry page does not show.
  • The macOS command hides two costs the README does not mention. The Homebrew formula depends on the dotnet formula, so it is a large install, and the bottle list covers Apple Silicon but appears not to cover Intel, which would mean an Intel Mac compiles. Both were judged too deep for an install table, and brew reports them at the prompt.
  • The Linux recommendation is Ubuntu-shaped. Snap is the shortest command but is not the best answer everywhere; Microsoft's own preferred route is the packages.microsoft.com apt/dnf repo, which is roughly eight lines and therefore not a table cell. The snapd caveat plus the link is the compromise.
  • Nothing here is tested by CI, which checks PowerShell and not prose. The install commands will rot silently, exactly as the Homebrew cask already did.

Feedback I want

  • Run one of the two commands on real hardware. That is the one gap I could not close, and it is the whole point of the change.
  • Argue with recommending community packages over Microsoft's own. I put the shortest working command in the table and Microsoft's instructions in the sentence beneath. The opposite ordering is defensible for a tool that handles live credentials.
  • Argue with the no-release call. The alternative is a 4.2.1 that ships an identical .ps1.

What is not done

  • No single-account guidance, which is what would actually have prevented the exchange that triggered this. README.md tells a reader with one account to use sca usage -Watch instead of sca monitor only inside the monitor section, where someone deciding whether to install will not reach it. Deliberately left out to keep this change to the Installation section.
  • No curl | sh bootstrap and no container recipe. Both were considered and rejected: the first breaks the "no companion assets" promise and adds a security surface, the second means mounting live OAuth credentials into a container for the sake of a TUI.
  • tools/install-powershell.sh is not recommended, despite existing, being Microsoft-copyrighted and handling both platforms in one line. It appears nowhere in Microsoft Learn, calls itself companion code for a blog, and is curl | bash as root that fetches a second script at runtime.

The Requisite table handed Windows `winget install Microsoft.PowerShell` and
the other two platforms a link to Microsoft's docs. That is backwards: Windows
is the one platform where pwsh often already exists, and the two where it never
does were the ones sent off to read. Both now carry a command verified against
its own registry, `brew install powershell` at 7.6.6 and `sudo snap install
powershell --classic` at 7.6.5 from Canonical, with the links kept as the
authority for when a command rots. That rot is not hypothetical: Homebrew's
powershell cask is already gone, so the `--cask` form that used to be correct
now 404s.

The rest removes friction found by walking the path a new user walks. The
download becomes a pasteable Invoke-WebRequest rather than a browser click.
"Without alias" becomes "Run it without installing" and moves ahead of the step
that edits your profile, because trying it without being touched is the thing a
reader wants first from a tool that manages OAuth credentials; it now also says
what `help` and `usage` actually do, `help` returning before anything is
resolved or created. The execution-policy fix gets a pointer from the first run
instead of living only at the far end of Platform Notes, and both invocation
examples use `./`, which pwsh accepts on every platform, in place of the
Windows-only `.\`.

Deliberately no changelog entry and no version bump: the script is byte-
identical, so a release here would ship an asset nobody's copy differs from.
@countzero
countzero merged commit 3dc74ec into main Sep 21, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant