Installation

This section describes how to install the Oneil CLI (Rust implementation) on Linux, Windows, and macOS. The recommended path for most users is to download a pre-built binary from GitHub Releases.

Option 1: Download a release from GitHub

Pre-built binaries are published on the Releases page for:

Linux — x86_64-unknown-linux-gnu (system, uv)
Windows — x86_64-pc-windows-msvc (system, uv)
macOS — aarch64-apple-darwin (Apple Silicon; homebrew, system, uv)

The CLI does not ship Python. Each archive is linked against a specific Python 3.12 layout. The VS Code / Cursor extension detects which layout you have and downloads that flavor. For a manual install, pick the matching archive:

homebrew — brew install python@3.12 (macOS)
system — python.org 3.12 on macOS, distro libpython3.12 on Linux, or Python 3.12 on PATH on Windows
uv — uv python install 3.12. The extension sets the library search path when it launches the CLI. For a PATH install, prefer Homebrew/system or build from source so the binary is linked to your uv prefix.

Pushing a version tag (for example v1.0.0) runs the Release workflow, which builds these archives and attaches them to the GitHub Release for that tag. In GitHub Actions, prefer careweather/oneil/actions/install-oneil (or model-test-report for full model-repo CI) — see Appendix C.

Linux / macOS

The release also attaches install-oneil.sh, which detects Homebrew / uv / system Python 3.12 and downloads that archive into ~/.local/bin:

curl -fsSL https://github.com/careweather/oneil/releases/latest/download/install-oneil.sh | bash
# or a specific tag:
curl -fsSL https://github.com/careweather/oneil/releases/download/v1.0.0/install-oneil.sh | bash

To pick the archive yourself:

Open the latest release.
Download the archive for your OS, architecture, and Python layout (for example oneil-v1.0.0-x86_64-unknown-linux-gnu-system.tar.gz or oneil-v1.0.0-aarch64-apple-darwin-homebrew.tar.gz).

Unpack and put the oneil binary on your PATH:

tar -xzf oneil-v*-x86_64-unknown-linux-gnu-system.tar.gz
sudo mv oneil /usr/local/bin/
# or, without sudo:
mkdir -p ~/.local/bin && mv oneil ~/.local/bin/
# ensure ~/.local/bin is in your PATH

Confirm:
```
oneil --version
```

Windows

Open the latest release.
Download the Windows zip for your Python layout (for example oneil-v1.0.0-x86_64-pc-windows-msvc-system.zip).
Unzip and either move oneil.exe into a directory on your PATH, or add the folder containing oneil.exe to your PATH.
Confirm in PowerShell or Command Prompt:
```
oneil --version
```

Option 2: Nix

If you use Nix with flakes enabled, you can run or install Oneil without a separate Rust or Python setup. The flake links against CPython 3.12 from nixpkgs and includes it at runtime.

To try Oneil without adding it to a system configuration:

nix run github:careweather/oneil -- --help
nix run github:careweather/oneil -- path/to/model.on

To install it, add the flake overlay and pkgs.oneil to your NixOS or home-manager configuration:

{
  inputs.oneil.url = "github:careweather/oneil";

  # nixpkgs.overlays = [ inputs.oneil.overlays.default ];
  # environment.systemPackages = [ pkgs.oneil ];           # NixOS
  # home.packages = [ pkgs.oneil ];                        # home-manager
}

The overlay also provides the VS Code / Cursor extension as pkgs.vscode-extensions.careweather.oneil. That package defaults oneil.serverPath to the flake-built CLI, so the editor uses the same CPython-linked binary as pkgs.oneil instead of downloading a GitHub Release. Example with home-manager:

{
  # nixpkgs.overlays = [ inputs.oneil.overlays.default ];
  # programs.vscode.profiles.default.extensions = [
  #   pkgs.vscode-extensions.careweather.oneil
  # ];
}

You can also build the extension with nix build github:careweather/oneil#oneil-vscode.

The first evaluation compiles from source. Contributors can use nix develop in the repository for the Rust toolchain, Python 3.12, and VS Code extension tools.

Prerequisites for building from source

The options below build Oneil yourself. You will need:

Rust: rustup — install and ensure cargo is on your PATH.
gcc
- Install on Fedora/RHEL: sudo dnf install gcc
- Install on Debian/Ubuntu: sudo apt install build-essential
Python 3.12 — the only CPython version Oneil supports. Needed at runtime when models import Python modules, and when building from source (development headers). Install it with one of:
- uv: uv python install 3.12
- Homebrew: brew install python@3.12
- Fedora/RHEL: sudo dnf install python3.12-devel
- Debian/Ubuntu: sudo apt install python3.12-dev
Helper .py files can import oneil because the CLI includes the Python library.

Option 3: Install from source using the install script

From the repository root, the install script builds the Rust CLI with default features (so models can import .py files and those files can import oneil).

git clone https://github.com/careweather/oneil.git
cd oneil
./install.sh

On Windows, use install.bat.

You need Python 3.12 (uv python install 3.12 or brew install python@3.12). The script prefers uv python find 3.12, then Homebrew python@3.12.

Option 4: Install from source with Cargo

Use this if you want the latest development version or need to customize the build.

Clone the repository:

git clone https://github.com/careweather/oneil.git
cd oneil

Build and install the oneil binary (requires Rust):
```
cargo install --path src/oneil
```
It places oneil in ~/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows); keep that directory on your PATH.

Building from source requires Python 3.12 (see Prerequisites).
Confirm:
```
oneil --version
```

Option 5: Run from the repository (development)

For day-to-day development without installing:

git clone https://github.com/careweather/oneil.git
cd oneil
cargo build -p oneil
./target/debug/oneil --version
# or run directly:
cargo run -p oneil -- path/to/model.on

Updating

Release binary: download the newer archive from Releases and replace the previous oneil binary on your PATH.
Nix: bump the oneil flake input in your configuration and rebuild.
From source: pull the latest code (or check out the new tag), then re-run ./install.sh or cargo install --path src/oneil.

Editor and tooling (optional)

VS Code / Cursor: Install the Oneil extension from the Marketplace for LSP and syntax highlighting, or install pkgs.vscode-extensions.careweather.oneil from this flake (see Option 2: Nix). The Marketplace extension can download the Oneil CLI from GitHub Releases (Command Palette: “Oneil: Install or Update CLI”, or “Oneil: Select CLI Version…” to install a different published tag). It picks the Homebrew, system, or uv archive that matches the Python 3.12 on the machine. Set oneil.serverPath only when you want to force a local build; that setting disables managed updates. The Nix package already sets oneil.serverPath to the flake-built CLI.
Vim: See the Vim support section in the main README for syntax highlighting.

Uninstalling Oneil

If Oneil was installed as a release binary, delete the release binary.

If Oneil was installed with Nix, remove pkgs.oneil from your NixOS or home-manager configuration and rebuild.

If Oneil was installed from source, run cargo uninstall oneil.

If the Python library was installed with pip, run pip uninstall oneil in the same virtual environment.

Troubleshooting

oneil: command not found
Ensure the directory containing the oneil binary is on your PATH.
Python-related build errors (from source) or oneil --version aborts
Install Python 3.12 to match the archive flavor you downloaded (brew install python@3.12, the python.org 3.12 installer, distro python3.12, or uv python install 3.12). See Prerequisites. The extension picks the flavor for you.
Permission denied (Linux/macOS)
After moving the binary, run chmod +x /path/to/oneil (or the path you used).
macOS: “cannot be opened because the developer cannot be verified”
Right-click the binary → Open, or remove the quarantine attribute: xattr -d com.apple.quarantine /path/to/oneil.

Keyboard shortcuts