Installation

Install Horus via curl, npm, or Homebrew. Verify, update, uninstall, and troubleshoot.

Horus runs on macOS and Linux. You can install the CLI through curl, npm, or Homebrew. The curl installer is recommended because it also installs the optional source-intelligence backend from the wheel bundled with the release.

System requirements

Node.js 22 or later — the Horus CLI is a Node binary.
No database to install — investigations and evidence persist in an embedded local store at ~/.horus.
Python 3.11+ and uv — only needed if you want the optional source-intelligence backend. The backend itself ships inside the Horus bundle, so Python and uv are the only prerequisite.
Git — used for change history, ownership signals, and project registration.

Zero infrastructure

The local store is embedded at ~/.horus — there is nothing to install or run. Migrating from an older local-Postgres setup? Run horus db import (it defaults to $DATABASE_URL) to bring your history across. Teams that want shared state use Horus Cloud.

curl installer (recommended)

bash

curl -fsSL https://horus.sh/install.sh | bash

The curl installer downloads the Horus CLI from GitHub Releases and installs the optional source-intelligence backend from the wheel bundled with the same release. The backend ships inside the Horus bundle — one bundle, one version — so nothing is installed from PyPI. It does not configure any production connectors.

What it does:

Detects your platform (macOS or Linux).
Downloads the CLI release.
Installs the CLI to a location on your PATH, usually ~/.local/bin.
Installs the source-intelligence backend from the wheel bundled with the same release, if Python 3.11+ and uv are present.

npm

bash

npm install -g @merittdev/horus

The npm package installs the CLI only. It does not install the source-intelligence backend. If you want source intelligence, install Python 3.11+ and uv, then run horus update — it installs the backend from the wheel bundled with the release. Run horus init to verify the backend is detected.

Homebrew

bash

brew install meritt-dev/tap/horus

The Homebrew formula installs the CLI only. Like npm, it does not install the source-intelligence backend automatically — run the curl installer or horus update to install it from the bundled wheel.

Verify the install

After installing, confirm the binary is available, then run horus init inside a repository you want to investigate.

bash

horus --version
horus init

horus --version prints the installed version. horus init starts by checking prerequisites — the optional source-intelligence backend — and prints fix-it hints for anything missing. The checks are advisory: they never fail init.

Update Horus

Use the same channel you installed with:

bash

# Simplest: built-in updater (works regardless of how you installed)
horus update

# Or use the same channel you installed with:
# If you used curl
curl -fsSL https://horus.sh/install.sh | bash

# If you used npm
npm update -g @merittdev/horus

# If you used Homebrew
brew upgrade meritt-dev/tap/horus

Uninstall Horus

How you uninstall depends on how you installed:

Channel	Command
curl	`rm ~/.local/bin/horus` (or wherever the installer placed the binary).
npm	`npm uninstall -g @merittdev/horus`
Homebrew	`brew uninstall meritt-dev/tap/horus`

Horus also stores configuration and data in a few places. Remove them if you want a clean uninstall:

~/.horus/ — global config, registry, source-intelligence state, and the embedded investigation store.
.horus/ in any initialized repository — project-local config.

Back up investigations before deleting `~/.horus`

Deleting ~/.horus removes the embedded store and its saved investigations. Export anything you want to keep first.

Platform-specific notes

macOS

The curl installer works on both Apple Silicon and Intel Macs.
Homebrew is supported through meritt-dev/tap/horus.
If macOS Gatekeeper blocks the binary, right-click it in Finder and choose Open, or remove the quarantine attribute with xattr -dr com.apple.quarantine /path/to/horus.

Linux

The curl installer supports common x86_64 and ARM64 distributions.
Make sure ~/.local/bin is on your PATH. Add it to ~/.bashrc or ~/.zshrc if needed.
You may need to install Node.js 22+ manually if your distribution ships an older version.

Troubleshooting

Symptom	Likely cause	Fix
`horus: command not found`	The install directory is not on your PATH.	For curl installs, add `~/.local/bin` to your PATH and restart your shell. For npm, check your global npm bin directory.
`horus investigate` cannot open the local store	A single-file build is missing its embedded-database assets.	Reinstall with the curl installer (`install.sh`) or `npm install -g @merittdev/horus` — the embedded store assets ship with those installs.
`horus init` reports source-intelligence backend missing	Python or uv is not installed, or the backend was not installed.	Install Python 3.11+ and uv, then re-run the curl installer or run `horus update` — the backend installs from the wheel bundled with the release. Init still writes the config and exits 0; indexing is skipped until the backend is present.
Permission denied during curl install	The installer cannot write to the target directory.	Check ownership of `~/.local/bin` or install to a custom prefix.
npm install fails with EACCES	npm permissions issue.	Use a Node version manager such as nvm or fnm, or fix npm permissions per npm docs.
Homebrew tap not found	The tap has not been added.	Run `brew tap meritt-dev/tap` before `brew install meritt-dev/tap/horus`.

Next steps

Once Horus is installed, follow the Getting started guide to run horus init in your first project and start an investigation.

PreviousInvestigation walkthrough NextCLI commands