Install and update One#

One is distributed as a self-contained release archive for each supported platform. The executable and its adjacent distribution/ directory form one installation: do not copy the executable away from the semantic packages, normalizers, analyzers, tools, and providers it resolves.

Verify before extraction#

Download the archive together with its .sha256, .sig, and .pem files. Verify both content and the release-workflow signing identity:

sha256sum -c one-<platform>.tar.sha256
cosign verify-blob \
  --certificate one-<platform>.tar.pem \
  --signature one-<platform>.tar.sig \
  --certificate-identity https://github.com/muijf/one/.github/workflows/release.yml@refs/tags/<version> \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  one-<platform>.tar

On macOS, use shasum -a 256 -c for the checksum. On Windows, use a SHA-256 tool that verifies the supplied checksum file and run the same cosign verify-blob identity check. A matching checksum without a valid signing identity proves only byte integrity, not release origin.

Extract into a versioned directory and add that directory—not the binary alone—to PATH. Confirm the selected command version:

one --version

Work offline#

After downloading and verifying the archive, its standard distribution works without network access. Project-specific registry packages and tools must already exist in the exact lock store or an imported bundle:

one bundle <BundleRef>
one sync --offline
one check --offline

The bundle command's definition and help identify whether the exact subject is being created, inspected, or imported; a bundle is never activated merely by being present on disk.

Offline mode never substitutes a nearby release, silently drops an input, or weakens admission because a registry is unavailable.

Update without changing projects implicitly#

Install a new verified archive beside the current version, inspect it, then change the user's explicit PATH or launcher selection. Installing a new One release does not rewrite project source, one.lock, local execution bindings, plans, artifacts, journals, or evidence.

Run the new executable against each project deliberately:

one sync
one check
one verify

sync shows any lock proposal caused by new package or tool selections. Do not accept that proposal merely because the executable changed. Pre-stable source changes use the one current grammar; update source and lock together rather than retaining parallel old and new project forms.

Roll back or uninstall#

To roll back the tool, restore the launcher or PATH selection to a previously verified intact archive. This does not roll back a deployed system or rewrite effects; release rollback follows an explicit recovery plan.

Uninstall by first selecting another installation, confirming no active daemon or shell session uses the old directory, and then removing that complete versioned archive directory. Project .one/ state belongs to each project and is not installation residue. Use one clean, one gc, or one reset local only according to their owner-aware retention rules.

Next: build your first system or read dependencies and toolchains.