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

No runtime required: a native binary for macOS (Apple silicon, Intel) and Linux (x86_64, ARM64, static musl). Source indexing installs its bundled Python backend with uv.
Node.js only if you keep a horus.config.ts/.js, or to run horus db migrate-from-ts once.
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 release archive for your platform from GitHub Releases, installs the horus binary, and installs the optional source-intelligence backend from the wheel in the same archive. 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 release archive for your platform and verifies its SHA-256 checksum.
Installs the CLI to a location on your PATH, usually /usr/local/bin or ~/.local/bin.
Installs the source-intelligence backend from the wheel in the same archive, 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 --force — 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 --force 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

# Built-in updater (v0.24 and later)
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

Refresh the agent skill after updating

Updating the binary does not rewrite a skill you already installed. v0.24.3 ships updated skill text; re-install it with horus skill install claude --force (or cursor / generic). For codex and gemini the target is your whole AGENTS.md or GEMINI.md, and --force overwrites that file, so run horus skill print codex (or gemini) and replace the Horus section by hand.

Upgrading from v0.23

On v0.23, horus update checks the old release feed and reports that you are up to date. Reinstall instead: re-run the curl installer, npm i -g @merittdev/horus@latest, or brew upgrade horus. Then run horus db migrate-from-ts once to copy your local history into the new store. It needs node and npx, and any running TypeScript horus processes and the watch service must be stopped first.

Uninstall Horus

How you uninstall depends on how you installed:

Channel	Command
curl	`rm /usr/local/bin/horus` or `rm ~/.local/bin/horus`, 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, credentials, registry, and the embedded investigation store; curl releases also keep their bundle under this directory.
.horus/ in any initialized repository — project config, encrypted connector secrets, source graph, and knowledge index.

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.

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	The local SQLite store at `~/.horus/horus-rust.db` cannot be created or opened.	Check that `~/.horus` exists and is writable by your user, and that no other process is holding the file. If the source-intelligence backend is missing, run `horus update --force`.
`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 --force` — 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	Your user cannot write to npm's global prefix.	Point npm at a user-owned prefix (`npm config set prefix ~/.npm-global`, then add `~/.npm-global/bin` to your PATH), or use the curl installer or Homebrew instead.
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