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 when you start an interactive session 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, then prints the result.
• --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

Update verification and recovery

Before replacing the installed binary, Polytoken verifies the signed release metadata, checks the downloaded archive against its SHA-256 checksum, and extracts and validates the new binary. On macOS, Polytoken also checks that the binary carries a Developer ID Application signature from the expected signing team. A failed verification leaves the installed binary unchanged.

During replacement, Polytoken keeps a backup and records progress so a later update or launch-time check can recover from an interrupted update by completing the replacement or restoring the backup.

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

Before starting a new interactive session, Polytoken checks the release channel for a newer version. Bare polytoken skips the check when attaching to an existing live session. The check also runs for polytoken new and polytoken continue, but their --no-attach variants skip the check. If a newer version is available, Polytoken prompts you before continuing.

For polytoken continue without a session ID, and equally for polytoken attach 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. Nominated attach (polytoken attach <session-id>) skips the check. 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. The network fetch has a five-second timeout, so an unreachable update server can delay the launch by at most five seconds but cannot block it. When you accept the prompt, Polytoken downloads and verifies the update, replaces the installed binary, and re-launches your command with the updated version. The re-launched process skips the update check for that run, so you are not prompted a second time. If you ran polytoken continue without a session ID, the re-launched command opens the session picker.

If the update check encounters a network failure, timeout, or other error before you accept an update, Polytoken continues the launch with the currently installed binary. When an update you accepted fails, Polytoken reports the error and stops the launch.

Polytoken keeps a record of the newest release metadata it has verified and rejects anything older, so an update check cannot lower the accepted release history. The record lives in $XDG_DATA_HOME/polytoken (default: ~/.local/share/polytoken). If polytoken update finds a corrupt record, the command stops before fetching and reports recovery guidance. Repair the record as directed, then run the update again. A launch-time check whose record is corrupt skips the network request and leaves the record unchanged.

Update configuration

The updates config block controls both the launch-time check and the polytoken update command, and 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.