relate upgrade

relate upgrade replaces the running relate binary with the latest release, after checking the release's checksum list against the signing key built into the binary. relate update is the same command. --check reports the installed and latest versions and changes nothing. Self-upgrade runs on macOS and Linux, on amd64 and arm64; it never opens a storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary. The release URLs on this page are the launch-day locations: before launch, nothing is published at them.

Synopsis

relate upgrade [--yes] [--check]
relate update  [--yes] [--check]

Options

Any other argument, such as --json, is a usage error (exit code 2).

What it checks

relate upgrade runs these steps in order and stops at the first that fails. A failure before the last step leaves the running binary as it was.

--check stops after step 3. The key is the one install.sh pins; the security reference gives it and the manual checks that match these steps. Steps 4 to 9 are described from the binary's source, not from a recorded run, because no release newer than the verified version exists to upgrade to.

Where it downloads from

GITHUB_TOKEN, when set, is sent as a bearer token on the requests for the three files and never on the request for releases.json, and is never printed. The release list request has no retry, no cache, and no fallback location.

Skill refresh

After the binary is replaced, relate upgrade runs relate skill install from the new binary for every detected agent, so the installed skillskill The SKILL.md cheat sheet and reference files a coding agent reads before it uses relate; relate skill install writes them. Read more in the glossary matches the new version:

The relate skill reference defines the states.

Output

Every successful outcome, --check included, prints its status lines and nothing after them; releases up to 0.1.1 also printed a two-line notice of the project's rename.

Every failure starts with Error: upgrade: on stderr and exits 1; a failed replace (step 8) adds a second line that names the reinstall command.

Errors and exit codes

When the release list cannot be read, the message names its URL, the reason, and the reinstall command:

Error: upgrade: could not read the release list from <url>: GET failed: <reason>; reinstall manually instead: curl -sSfL https://relatedb.ai/install.sh | GITHUB_TOKEN=$(gh auth token) bash

Examples

The --check runs on this page were recorded with RELATE_RELEASES_JSON_URL pointing at a copy of releases.json served from the local machine, so they needed no network. With the latest release equal to the installed version:

relate upgrade --check

current version: 0.1.2
latest release:  0.1.2
relate is up to date

With the copy edited to list a higher version, v0.99.0, the report names it and nothing is downloaded:

current version: 0.1.2
latest release:  0.99.0
upgrade available: run `relate upgrade` to install 0.99.0

A run that cannot reach the release list exits 1. This one had RELATE_RELEASES_JSON_URL=http://127.0.0.1:8874/releases.json with nothing listening; the text after io: comes from the operating system, and this recording is from macOS:

Error: upgrade: could not read the release list from http://127.0.0.1:8874/releases.json: GET failed: io: Connection refused (os error 61); reinstall manually instead: curl -sSfL https://relatedb.ai/install.sh | GITHUB_TOKEN=$(gh auth token) bash

A flag the command does not take is a usage error:

relate upgrade --json
echo "exit=$?"

Error: unexpected argument to upgrade: --json
Usage: relate upgrade [--yes] [--check]
Run 'relate upgrade --help' for more information.
exit=2

See also

• Install relate: the first install, with the same signature check
• Security: the signing key and the manual verification steps
• relate skill: the skill copies the upgrade refreshes
• Upgrade a store: what a new release does to a store written by an older one
• Problems relate solves: offline and sandboxed use: the commands that reach the network