Installation

Install with GitHub CLI

You do not need Rust to use Olyx in development, CI, or a deployed application. Install the prebuilt executable for your operating system. Rust is only needed when changing Olyx’s source code and compiling it yourself.

Download a prebuilt executable with GitHub CLI. gh is needed only for downloading; running Olyx requires no Rust, Cargo, Node.js, Python, or database server. SQLite is bundled. External plugins may have their own runtime requirements.

The prepared CLI release has not been published yet. These commands require a published release with matching binary assets; they do not download GitHub’s source-code archives or build the CLI.

Linux and macOS

Run in a new download directory. The command selects your operating system and CPU, downloads the latest published binary and its checksum, verifies it, and installs the executable without sudo:

repo=Olyx-labs/Olyx-CLI
version=$(gh release view --repo "$repo" --json tagName --jq .tagName) || exit 1
case "$(uname -s)/$(uname -m)" in
  Linux/x86_64) target=x86_64-unknown-linux-musl ;;
  Linux/aarch64|Linux/arm64) target=aarch64-unknown-linux-musl ;;
  Darwin/arm64) target=aarch64-apple-darwin ;;
  Darwin/x86_64) target=x86_64-apple-darwin ;;
  *) echo "Unsupported platform" >&2; exit 1 ;;
esac
asset="olyx-${version}-${target}.tar.gz"
gh release download "$version" --repo "$repo" \
  --pattern "$asset" --pattern "$asset.sha256" || exit 1
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c "$asset.sha256" || exit 1
else
  shasum -a 256 -c "$asset.sha256" || exit 1
fi
tar -xzf "$asset" || exit 1
mkdir -p "$HOME/.local/bin"
install -m 0755 "olyx-${version}-${target}/olyx" "$HOME/.local/bin/olyx"
export PATH="$HOME/.local/bin:$PATH"
olyx --version

Add the PATH setting to your shell profile if needed. The extracted directory also contains examples and documentation. Published releases include a Sigstore bundle for optional provenance verification; follow the release’s README.

Windows PowerShell

Use the Windows x86_64 executable:

$ErrorActionPreference = "Stop"
$repo = "Olyx-labs/Olyx-CLI"
$version = gh release view --repo $repo --json tagName --jq .tagName
if ($LASTEXITCODE -ne 0) { throw "No downloadable release found" }
$name = "olyx-$version-x86_64-pc-windows-msvc"
$asset = "$name.zip"
gh release download $version --repo $repo --pattern $asset --pattern "$asset.sha256"
if ($LASTEXITCODE -ne 0) { throw "Release download failed" }
$expected = ((Get-Content "$asset.sha256") -split '\s+')[0]
$actual = (Get-FileHash $asset -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "Archive checksum mismatch" }
Expand-Archive $asset -DestinationPath .
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Olyx\bin"
Copy-Item "$name\olyx.exe" "$env:LOCALAPPDATA\Olyx\bin\olyx.exe"
$env:PATH = "$env:LOCALAPPDATA\Olyx\bin;$env:PATH"
olyx --version

The PATH change applies to this session. Add the installation directory to your user PATH for future terminals.

Select a release

List available releases and replace TAG with the one to download:

gh release list --repo Olyx-labs/Olyx-CLI
gh release view TAG --repo Olyx-labs/Olyx-CLI

For a pinned installation, set version=TAG in the Unix example or $version = "TAG" in PowerShell instead of resolving the latest release.

Download without GitHub CLI

Download the matching binary archive and .sha256 file from GitHub Releases, then verify, extract, and install using the same steps above. Never install a source-code archive as if it contained a prebuilt binary.

Build from source (contributors)

Install Rust 1.88 or newer and a C compiler for bundled SQLite, then run:

git clone https://github.com/Olyx-labs/Olyx-CLI.git
cd Olyx-CLI
cargo build --locked --release --bin olyx
./target/release/olyx --version
./target/release/olyx check examples/olyx.json

The Windows binary is target\release\olyx.exe. SQLite is compiled into the binary; no database server or separate SQLite runtime installation is required.

Upgrade

Replace the binary with a verified newer release, confirm olyx --version, and run olyx check against your configuration. Back up persistent trace storage before upgrading. Keep the configuration and database outside the extracted release directory if you routinely replace that directory.

olyx --version
olyx check olyx.json
olyx doctor --config olyx.json

Continue with the quickstart.

Test the source checkout without provider accounts

With Rust/Cargo, a C compiler, and Python 3 installed, run:

./scripts/test-providers

This builds the CLI and runs local fixtures and contract checks. It makes no live provider calls. See Testing and verification for details.