Installation

Install the one binary onto your PATH. It should take only a few seconds.

For: first-time install, upgrade / downgrade, custom install location, uninstall.

You will finish with: one --version working in your shell, plus a clear understanding of upgrade semantics and installer environment variables.

macOS / Linux One-line Install

curl -fsSL https://1cli.dev/install.sh | bash

The script:

1. Detects $os/$arch (darwin / linux, amd64 / arm64)
2. Resolves the latest version from the GitHub Releases latest redirect
3. Downloads the matching tarball from release assets and verifies SHA256
4. Extracts one into ~/.local/bin/one
5. Tells you if PATH needs an update

Audit the script: open https://1cli.dev/install.sh in a browser. It is plain text.

Verify after installation:

one --version
# 0.1.1 (or later)

If PATH is missing, the script will tell you what to add:

# zsh:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# bash:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Open a new shell.

Windows PowerShell Install

Windows 10/11 x64 users can install from PowerShell:

irm https://1cli.dev/install.ps1 | iex

The script downloads one-cli_windows_amd64.zip, verifies it against checksums.txt, installs one.exe under %LOCALAPPDATA%\Programs\one\bin, and adds that directory to your user PATH. Open a new terminal after the first install.

Audit the script: open https://1cli.dev/install.ps1 in a browser. It is plain text.

Manual Download

Download the matching archive from GitHub Releases, unpack it, and put one (or one.exe) on PATH. Windows currently publishes an x64 archive; macOS and Linux publish x64 and arm64 archives.

Example for Linux amd64:

curl -L -o one.tar.gz \
  https://github.com/1cli-team/one-cli/releases/latest/download/one-cli_linux_amd64.tar.gz
tar -xzf one.tar.gz
mv one ~/.local/bin/
one --version

On Windows, the archive is one-cli_windows_amd64.zip.

Automatic Updates

Stable release builds start an independent background updater at most once every 24 hours during normal terminal use. It downloads the platform archive and checksums.txt from the official GitHub Release, verifies SHA256 and the executable version, then replaces the installed program. The current command keeps running; subsequent invocations use the new version. On Windows, replacement waits for the command that started the update to exit.

Download, verification, or write failures preserve the installed program. When a newer release is known, One shows the failure and a manual update command. If the executable changes during the download, such as after a local rebuild, the updater refuses to overwrite it. Failed attempts also retry on the 24-hour interval.

Development builds skip update checks, downloads, installation, and notifications entirely. Builds from go build, mise run build, mise run build-local, and mise run install default to updates disabled, even when RELEASE_VERSION is set. Only the release packager enables the update marker, and a complete stable version is also required. Development, local, snapshot, and other prerelease versions never update automatically.

CI, structured JSON/YAML output, --dry-run, and internal task processes do not start updates. Update state lives at $XDG_CACHE_HOME/one/update-check.json, defaulting to ~/.cache/one/update-check.json.

Upgrade And Downgrade

install.sh and install.ps1 check the installed one --version before deciding what to do:

Current state	Behavior
Not installed	Install
Target is newer	Upgrade automatically
Target is the same	Skip; set ONE_FORCE=1 to reinstall a damaged binary
Target is older	Refuse downgrade; set ONE_FORCE=1 if you intentionally want to downgrade

For normal upgrades, rerun the install command. Use ONE_FORCE only for downgrade or repair.

mise Runtime

One does not bundle mise. When a command needs it, One uses an explicit ONE_MISE_BINARY first, then a compatible mise on PATH (minimum 2026.9.7), then its own verified installation. If none is available, it downloads the pinned official mise 2026.9.7 release, verifies both archive and executable SHA256, and installs it atomically. Supported targets are macOS/Linux x64 and arm64, and Windows x64; Linux uses musl releases. Official distribution.

Selection happens again on each invocation. Removing system mise switches to the managed runtime; a missing or damaged managed executable is repaired automatically. A compatible system installation takes priority again when restored. Invalid explicit overrides report an error instead of falling back. No shell activation is required.

Managed content	Default location	Root override
mise executable	~/.local/share/one/runtimes/mise/<version>/<platform>/	XDG_DATA_HOME
Tools and plugins	~/.local/share/one/mise/	XDG_DATA_HOME
Global configuration	~/.config/one/mise/	XDG_CONFIG_HOME
State and trust records	~/.local/state/one/mise/	XDG_STATE_HOME
Disposable cache	~/.cache/one/mise/	XDG_CACHE_HOME

The same effective Home convention applies on Windows. XDG roots must be absolute. For managed mise, One sets MISE_DATA_DIR, MISE_CONFIG_DIR, MISE_STATE_DIR, and MISE_CACHE_DIR in the child environment, replacing inherited values. External mise retains its existing directory settings. Project configuration stays in the project. Switching to managed mise can require reinstalling tools and granting trust again; One does not copy external configuration or trust records.

Managed mise updates with One; automatic self-updates are disabled for that child process. Manually replacing it with mise self-update causes the next invocation to restore the pinned executable. A verified executable from an older One cache can be migrated without downloading, preserving the old file. Cache cleanup does not remove tools or trust records.

Offline use: a valid external, managed, or migratable legacy executable can be reused offline. A fresh environment without any of them needs network access. Prepare mise and the required tools/dependencies beforehand, or point ONE_MISE_BINARY to a compatible external executable. ONE_RUNTIME=builtin is a temporary diagnostic escape hatch using existing tools.

Download, migration, or verification failures return MISE_INSTALL_FAILED. Check network/proxy access to GitHub Releases and permissions on One's runtime directory, then retry the same command. Help, dry-run, and configuration planning do not prepare mise. Creation and project addition prepare it to trust complete One-generated configurations; a failure returns a warning while preserving the generated files.

Use one mise --version, one mise doctor, or one mise trust <config-path> to work with the same selected runtime. Creation and project addition register file-specific trust for complete One-generated configurations, including with MISE_PARANOID=1. Custom configuration still requires review and follows mise’s trust policy. Arguments, IO, and exit codes are forwarded, without One project secrets; use one exec when those secrets are needed.

Infisical login

Run one login to sign in with a browser. The session is saved in your system keyring. See login and shared credentials.

Environment Variables

Both installers accept the variables below. PowerShell reads them from $env:NAME; its default install directory is %LOCALAPPDATA%\Programs\one\bin.

Variable	Default	Meaning
ONE_VERSION	resolved from the latest GitHub release	Lock the version, for example v0.1.1
ONE_INSTALL_DIR	$HOME/.local/bin; Windows: %LOCALAPPDATA%\Programs\one\bin	Install directory
ONE_FORCE	0	Set to 1 to allow downgrade, same-version reinstall, or overwrite a binary whose version cannot be read
ONE_REPO_URL	https://github.com/1cli-team/one-cli	GitHub repo URL override for debugging
ONE_RELEASE_BASE_URL	$ONE_REPO_URL/releases/download	Release asset download base override
ONE_LATEST_URL	$ONE_REPO_URL/releases/latest	Latest release resolver override
ONE_SKIP_VERIFY	0	Set to 1 to skip SHA256 verification; debugging only
ONE_NO_PATH_UPDATE	0	Set to 1 to install without changing the user PATH

Install a specific older version into a custom directory:

curl -fsSL https://1cli.dev/install.sh | ONE_VERSION=v0.1.0 ONE_INSTALL_DIR=/opt/bin bash

Uninstall

PowerShell:

Remove-Item "$env:LOCALAPPDATA\Programs\one\bin\one.exe"

macOS / Linux:

rm ~/.local/bin/one

Run one logout to remove the active session from the system keyring.

Local Repo Build For Contributors

If you are changing One CLI itself, read CONTRIBUTING.md. Short version:

git clone https://github.com/1cli-team/one-cli
cd one-cli
brew install mise     # macOS; adapt for Linux
mise run install                 # package Dashboard + CLI, then create a native launcher
hash -r
which one
one --version

Windows creates ~/.local/bin/one.exe; when file symlinks are unavailable, it falls back to a one.cmd forwarding shim. The extensionless one symlink created by older versions is migrated safely.

For the full contributor flow, see CONTRIBUTING.md. For command-surface reference, see Command overview.

Installed?

Go to Quick start and create your first workspace.