Update Notifications

Update Notifications

nself can print one line on stderr when a newer CLI release exists. It is off by default: nothing is sent and nothing is printed until you opt in.

---

Turn it on

export NSELF_UPDATE_CHECK=1

Only the value 1 enables it. Put the line in your shell profile to keep it.

What you see

After a command succeeds, at most once every 24 hours:

A newer nself is available (current 1.4.12, latest 1.5.0). Run `nself update` to upgrade.

nself update --check is unchanged and still reads GitHub releases. Use it for the full answer.

The hint is never printed when any of these is true:

• NSELF_UPDATE_CHECK is not 1
• the command failed
• JSON mode is on: --json, or --format json / --output json (any case). This holds for older commands too, even those that do not use the JSON envelope
• stderr is not a terminal (pipes, redirects, cron)
• a CI marker is set: CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE or JENKINS_URL (CI=false and CI=0 do not count)
• the command is nself update itself
• the cached latest version is empty, not a plain MAJOR.MINOR.PATCH release, or not newer than yours

It writes to stderr only. stdout is never touched.

What is sent

When opted in and the cache is older than 24 hours, a background goroutine makes one request:

GET https://ping.nself.org/version
User-Agent: nself/<your version>

There are no other headers (compression is off, so there is no Accept-Encoding). No account, project, licence key or machine id is included. The request has a 250 ms budget. A slow or failing network never delays the command and never prints anything; the goroutine is simply abandoned when the command ends.

The ping handler stores nothing. ping.nself.org's web proxy does log the client IP address and the User-Agent line like any web server. That is the reason the check is opt-in.

The cache

~/.nself/cache/update-check.json (mode 0600):

Field	Meaning
checked_at	time of the last refresh attempt, good or failed
latest	last good answer from ping
last_error	why the last refresh failed; empty after a good one
hinted_at	when the hint was last printed
attempted_at	when a refresh was last started, written before the request goes out

A failed refresh keeps the old latest, records last_error, and is not retried for 24 hours. A refresh that is cut short because the command ended first records no checked_at. The attempted_at written before the request keeps the retry to once an hour: no new request starts within 1 hour of the last attempt. If the cache cannot be written, no request is made. A corrupt file is replaced. Delete the file to reset it.

The hint itself reads only this file. It never touches the network.

When a command is about to refresh a stale cache, it decides the hint first, from the cache as it was before the refresh. The answer that refresh brings back shows up on a later command, never on the one that fetched it. A hint decided this way counts as that day's hint even if the command then fails, so a failed command can use up the day's hint without printing it.

Related

• Command-Canon
• Compat-V15