No. Check at most once a day, run the check in the background so it never delays the command, stay silent in CI and when offline, and give users a clear setting to turn it off. An update check is a network call from a tool that people expect to behave predictably.
Notify versus install
An update check can only tell the user a new version exists. An auto-update installs it. These are different risks.
A notice carries little risk, as long as the text comes from your server and cannot be used to trick the user into running something else. An auto-install changes code on the machine and needs the full set of protections, such as signed releases and a rule against going backwards. For that decision, see should an internal developer tool auto-update.
Rules for the check
- Rate limit it. Store the time of the last check in user config and skip if it was under a day ago.
- Run it in the background. Homebrew's public documentation describes the same idea for analytics: requests go out in a detached background process with a short timeout, and failures are silent so they do not delay the requested operation. Apply that to update checks.
- Short timeout, silent failure. A slow network must not slow the command.
- Skip it in CI. Pipelines should use pinned versions, and an update notice in a log wastes space and can confuse people. Detect common CI environment variables and turn the check off.
- Skip it when not on a terminal. If output is piped to another program, do not print notices into it.
- Do not send identifying data. The request needs the current version and platform, nothing about the project or user.
- Offer one setting to disable it. Document it in help and in your docs, and honour it everywhere.
Where the notice goes
Print it to standard error, once per run at most, and keep it to one line with the new version and the command to update. Do not print release note text fetched from the server, since it could contain terminal escape sequences.
Air-gapped and enterprise use
Many companies block outbound calls from developer machines or route them through a proxy. Your tool should work with the check disabled by configuration, and should respect proxy settings when it is enabled. Provide a way for administrators to set the policy once for all users.
| Environment | Recommended behaviour |
|---|---|
| Developer laptop | Daily background check, one-line notice |
| CI | Off by default, version pinned |
| No terminal attached | Off |
| Offline | Fails silently |
| Managed enterprise | Admin setting wins |
Test the unhappy paths
Run the tool with the network unplugged, with a proxy that hangs, and with a server that returns garbage. Each time the command itself should finish normally and at normal speed. A tool whose update check can slow or break the real work will get the check disabled by users, and then nobody sees the notice.
Quick check
Is an update check the same as auto-update?
No. A check only reports a new version. Installing code is a bigger decision and needs signature and downgrade protection.
Why print the notice to stderr?
Scripts parse standard output. Notices on stderr will not corrupt it.
Safeguard's CLI installers are listed on its download page, and the free scan is at gold.safeguard.sh/scan.
Sources
Last reviewed: 19 October 2026.
