One-liner scripts (no Node required)

Both scripts pull the latest GitHub Release binary for your platform, put it somewhere writable and add that directory to your PATH, so hfo works in the next terminal with no follow-up. No sudo, no admin prompt.

Variable	Effect
`HFO_VERSION=v0.2.0`	Pin a specific tag instead of the latest release
`HFO_INSTALL_DIR=/some/dir`	Install somewhere other than the default
`HFO_NO_MODIFY_PATH=1`	Print the PATH line instead of writing it to your profile (shell script only)

# Detects macOS/Linux + arch, installs to /usr/local/bin or ~/.local/bin, # updates your shell profile, and clears the macOS quarantine flag. $ curl -fsSL https://hfo.carrillo.app/install.sh | sh

# Installs to %LOCALAPPDATA%\Programs\hfo and adds it to user PATH. No admin needed. PS> irm https://hfo.carrillo.app/install.ps1 | iex

Binaries are built only when a v*.*.* tag is pushed, never on regular commits. CI runs typecheck + lint + test + build on every commit, but release artifacts are reserved for tagged versions.

Package managers

All four publish the same hfo-cli package. Node.js ≥ 22 required.

$ npm i -g hfo-cli $ pnpm add -g hfo-cli $ yarn global add hfo-cli $ bun add -g hfo-cli

Standalone binaries

Each tagged release publishes self-contained executables — no Node runtime required. Download and drop on your PATH.

Asset	OS · Arch
`hfo-linux-x64`	Linux x64 (glibc)
`hfo-linux-arm64`	Linux arm64 (Raspberry Pi 4/5, Graviton, etc.)
`hfo-macos-x64`	macOS x64 (Intel)
`hfo-macos-arm64`	macOS arm64 (Apple Silicon M1+)
`hfo-win-x64.exe`	Windows x64
`hfo-win-arm64.exe`	Windows arm64 (Snapdragon X, Surface Pro 11)^*

^* First published in v0.2.1. On Windows ARM you can also use npm i -g hfo-cli — the package is plain JavaScript and runs natively.

Which macOS build do I need?

Apple Silicon (M1 and later) takes arm64; Intel Macs take x64. If you are unsure, ask the machine — the one-liner above picks for you automatically.

$ uname -m arm64 # Apple Silicon -> hfo-macos-arm64 x86_64 # Intel -> hfo-macos-x64

Running the Intel build on Apple Silicon works through Rosetta 2, but it gives up the unified-memory GPU detection hfo relies on for scoring — every model would look CPU-only. Pick the native arm64 asset.

$ curl -LO https://github.com/carrilloapps/hfo/releases/latest/download/hfo-linux-x64 $ chmod +x hfo-linux-x64 $ sudo mv hfo-linux-x64 /usr/local/bin/hfo $ hfo --version

$ curl -LO https://github.com/carrilloapps/hfo/releases/latest/download/hfo-macos-arm64 $ chmod +x hfo-macos-arm64 # Clear the quarantine flag if the file came from a browser (see below) $ xattr -d com.apple.quarantine hfo-macos-arm64 || true $ sudo mv hfo-macos-arm64 /usr/local/bin/hfo $ hfo --version

Verify the install

$ hfo --version hfo v0.2.1 · MIT · José Carrillo # Print hardware profile and recommended picks $ hfo --view # Launch the fullscreen TUI $ hfo

Troubleshooting

Command not found after install

If hfo: command not found appears immediately after the install script, the install directory isn't on your PATH yet.

macOS / Linux: open a new terminal. The script appends the PATH line to the profile your shell actually reads — ~/.zprofile for zsh (the macOS default), ~/.bash_profile for bash on macOS, ~/.bashrc for bash on Linux, ~/.config/fish/config.fish for fish, else ~/.profile. To apply it in the current shell, source that file.
Windows: close and reopen PowerShell. The PATH change is per-user and takes a new session.
Global npm: check npm prefix -g — that directory's bin subfolder must be on PATH.

macOS: “cannot be opened because the developer cannot be verified”

The standalone binaries are not code-signed or notarised. When a file is downloaded through a browser, macOS attaches a com.apple.quarantine attribute, and Gatekeeper then refuses to run it. The one-liner installer clears the attribute for you; a manual download needs one command:

$ xattr -d com.apple.quarantine /usr/local/bin/hfo # Confirm nothing is left on the file $ xattr /usr/local/bin/hfo

If you already hit the dialog, you can also allow it once from System Settings → Privacy & Security, where the blocked binary appears with an Open Anyway button. Prefer npm i -g hfo-cli if you would rather not run unsigned binaries at all — the npm package is plain JavaScript executed by your own Node install.

macOS: hfo reports the wrong VRAM on Apple Silicon

Apple Silicon has no discrete VRAM; the GPU draws from unified memory. hfo derives the usable budget from the iogpu.wired_limit_mb sysctl when you have set one, and otherwise from a conservative share of total RAM. To check or override it:

# 0 means "system default" — hfo then uses its own tiered estimate $ sysctl iogpu.wired_limit_mb # Tell hfo exactly how much to assume, in MiB $ HFO_VRAM_MIB=49152 hfo --view

Ollama not found

hfo doesn't require Ollama to already be installed. On first run, if it's missing, you'll see an installer overlay offering the platform-appropriate method (winget install Ollama.Ollama, brew install ollama, or the official curl | sh). Confirm with Enter, or install manually and re-run hfo.

Node version mismatch

All four package managers require Node.js 22 or newer. Check with node -v. Upgrade via nvm (Unix), fnm, or n. The standalone binaries have no Node dependency.

Corporate proxy / mirror

If npm can't reach the registry, set your proxy first:

npm config set proxy       http://your-proxy:8080
npm config set https-proxy http://your-proxy:8080
npm config set registry    https://your-registry.example.com/

Or use the standalone binary — it only contacts GitHub Releases (one HTTPS request) and then Hugging Face at runtime.

SELinux / AppArmor blocking nvidia-smi

Hardware scoring calls nvidia-smi to read VRAM. If the binary runs confined, the call silently fails and GPU scoring returns zero. Either run hfo unconfined or pre-populate settings.modelDir and skip the scoring step by passing --dir.

Uninstall

# via npm / pnpm / yarn / bun $ npm uninstall -g hfo-cli # standalone binary on Linux / macOS — the installer picks whichever is writable $ sudo rm /usr/local/bin/hfo $ rm ~/.local/bin/hfo # Windows (PowerShell) PS> Remove-Item "$env:LOCALAPPDATA\Programs\hfo" -Recurse -Force

Settings file (settings.json) and model downloads are untouched. Remove them manually if desired:

Windows — %APPDATA%\hfo\
macOS — ~/Library/Application Support/hfo/
Linux — ~/.config/hfo/