Skip to main content
ChatCLI keeps itself current. It detects which channel the running binary was installed through and applies updates through that exact channel — it never crosses channels, never fights your package manager, and never touches a build it didn’t produce.

​
Install-Channel Detection

Detection runs locally (no network) by combining the binary’s real path, the Go build metadata and the version stamp injected by the release CI:
The Homebrew check runs first on purpose: the bottle installed by the tap is the same stamped asset published on the GitHub release, so only the Cellar path distinguishes the two channels.

​
Why source builds are never auto-updated

A locally compiled binary may carry uncommitted patches. Replacing it with a release artifact would silently destroy that work, so ChatCLI only prints the way forward:

​
The /update Command

Bare /update is an explicit request: when a newer release exists on an automatable channel, it applies immediately — the same semantics as brew upgrade.
Before applying anything — and on /update check — ChatCLI shows the What’s new section: the highlights parsed straight from the GitHub release notes, which arrive in the same API response as the version check (no extra network call). /update check reports the same status but never applies anything. The same card backs /version and the -v/--version flag: installed build, detected install channel, latest release, the invitation to /update (plus the channel-native command when there is one) and the what’s-new section whenever an update exists. The command is also available from the interactive command palette and the tab completer, and /config update shows the resolved policy at any time.

​
Verified Self-Replace

When the binary came straight from a GitHub release, ChatCLI updates it in place with a hardened pipeline:
  1. Downloads checksums.txt from the target release.
  2. Streams the platform asset to a staging file in the same directory as the binary (guaranteeing an atomic rename on the same filesystem) while computing its SHA-256.
  3. Refuses the install on any checksum mismatch — the download is discarded and the current binary is never touched.
  4. Swaps atomically: a plain rename on macOS/Linux (the running process keeps its old inode), or the rename-to-.old dance on Windows with automatic rollback if activation fails. Leftover artifacts are cleaned on the next boot.
Releases published before checksums.txt existed cannot be verified, and ChatCLI refuses unverified installs — you’ll get a manual-download instruction instead. This only affects updating to very old releases.
If the install directory isn’t writable (say, /usr/local/bin owned by root), the updater degrades to a copy-paste command:

​
Background Auto-Update (Staging)

Set CHATCLI_AUTO_UPDATE to control the boot-time behavior: Auto mode uses staging, the same model as Claude Code: the running process is never restarted or interrupted. The new binary lands on disk while you work, and the next start opens on the new version — announced once on the welcome screen:
In notify mode (the default) the welcome screen shows the invitation instead — the same one the /version card renders, including the native command of your detected install channel:
The banner is both instant and current: it trusts the last known release data even past the daily re-check window, and when that cache is stale the boot gives the refresh a short synchronous budget (about 1.5 s) before printing — so a release published overnight shows up on the very first banner, not one boot later. A fresh cache (at most one query per day) costs nothing, and off mode skips the network entirely. Only when the check can’t finish inside the budget (slow or absent network) does the announcement fall back to the running session, at the next prompt turn — you still don’t have to restart (or run /version) to find out:
The same in-session notice fires in auto mode when the silent staging fails (for example, the module proxy is unreachable), so a broken background update never hides a new release from you.
Homebrew is deliberately excluded from silent background updates. brew upgrade takes Homebrew’s global lock and can trigger a full brew update; ChatCLI only drives it when you explicitly run /update. Concurrent ChatCLI processes coordinate through a lock file, so only one performs the background update.

​
Configuration

​
Troubleshooting