Updating Polytoken

Polytoken can update itself. The polytoken update command checks the configured release channel and applies an update when a newer version is available. Polytoken also checks for updates automatically at launch and prompts you if one is available.

The polytoken update command

Run polytoken update to check the configured channel and apply the update if a newer version is available. If Polytoken cannot load the config, Polytoken prints a warning to stderr and uses the default channel latest instead of stopping.

polytoken update

Flags

• --channel latest|stable overrides the updates.channel config value for this invocation. Passing --channel skips config loading entirely, so the command works even when the config cannot load.
• --target-version <version> installs a specific version. This bypasses the newer-than check, so you can use it to downgrade.
• --check checks for an available update without applying it. Prints whether an update is available and exits.
• --format human|json controls the output format. human (the default) prints progress messages. json emits structured JSON to stdout.

Exit codes

Apply mode (polytoken update without --check):

Code	Meaning
0	Updated, or already current
2	Error

Check mode (polytoken update --check):

Code	Meaning
0	Already current
1	Update available
2	Error

Development builds

Development builds report version 0.0.0-dirty. Polytoken treats published releases as newer than that development version, so an update can replace your development build with a published release. Set updates.automatic_check to false to stop launch-time update checks while using a development build.

Launch-time update check

When you start an interactive session, Polytoken checks the release channel for a newer version before the session begins. The check covers polytoken, polytoken new, and polytoken continue. If a newer version is available, Polytoken prompts you before continuing.

For polytoken continue without a session ID, Polytoken checks for updates before opening the session picker. Polytoken also performs the check when no resumable sessions exist, so the update prompt can appear before Polytoken reports that it found no sessions. Every other command skips the check. Stdin and stderr must both connect to a terminal, so scripts and pipelines run without a prompt.

Polytoken performs the check at most once every 24 hours. A 5-second timeout on the network fetch means an unreachable update server does not delay the session. When you accept the prompt, Polytoken downloads and verifies the update, replaces the installed binary, and starts the session again with the updated version. The re-launched process skips the update check for that run, then opens the polytoken continue session picker once.

A network failure, timeout, or update error does not block or crash the launch. Polytoken proceeds with the currently installed binary.

Polytoken keeps an anti-rollback sequence floor in the data directory. The floor combines the current update state with sequence information from older launch-check records, so an update check cannot lower the accepted release history. If polytoken update finds a corrupt sequence record, the command stops before fetching and reports recovery guidance. Repair the record as directed, then run the update again. A launch-time check skips its network request when the same record is corrupt and leaves the record unchanged.

Update configuration

The updates config block controls both the launch-time check and the polytoken update command. The updates block is global-only: project configs may not set any keys under it.

Key	Default	Description
updates.automatic_check	true	Whether Polytoken checks for updates at launch. Set to false to disable the launch-time check. The polytoken update command still works when updates.automatic_check is false.
updates.channel	latest	The release channel to track. latest follows the newest published release. stable follows only stable releases and skips unstable pre-releases.