Install

Pre-1.0

Harnery is still pre-1.0; the API surface is settling. Pin a specific minor version (harnery@^0.31.0) and read the CHANGELOG before each upgrade.

Requirements

• Node 20.19+ or Bun 1.3+: either runtime works
• A POSIX shell (Linux, macOS, or WSL)

The published npm package ships a prebuilt dist/, so it runs on plain Node out of the box, no Bun required. Installing Bun is optional but recommended for developing Harnery: Bun runs the TypeScript source directly (zero build step), so edits are live. The package’s exports resolve to TS source under Bun and to the built dist/ everywhere else, so the two stay in lockstep.

One Bun-only command

harn tunnel is the single exception: its reverse-proxy gate worker is a Bun.serve process, so that one command requires Bun installed. It fails with a clear message on a Bun-free host. Everything else runs on Node.

Install

One line, no clone needed:

curl -fsSL https://harnery.com/install.sh | bash

It installs the harn CLI globally with a package manager you already have (npm preferred for a predictable global bin, Bun otherwise), checks that bin dir is on your PATH, verifies harn --version, and points you at harn init. It’s non-interactive and idempotent, so it’s safe to pipe and safe to re-run.

Prefer to drive your package manager yourself? Same result:

npm

npm install -g harnery

bun

bun add -g harnery

project dep

npm install harnery   # then run it with: npx harn …

Pass flags to the one-liner through bash -s --:

curl -fsSL https://harnery.com/install.sh | bash -s -- --method bun --version 0.3.2

--version (or HARNERY_VERSION) pins a version, --method npm|bun forces a package manager, and --install-runtime installs Bun when neither Bun nor Node is present (without it, the installer prints how to get a runtime and exits). It’s served straight from the docs site, so you can read it before running: harnery.com/install.sh.

What npm gives you vs a git clone

npm install harnery (what the one-liner runs) ships the CLI + coord engine (bin, dist, src, schemas): everything you need to wire hooks with harn init and run the coord layer. It does not include the web/ dashboard or this docs/ site; those are heavy app/build trees that live in the git repo only.

To run the dashboard (harn web up) or hack on Harnery itself, clone the repo (next section).

From a git clone (contributing or the dashboard)

Cloned the repo? One script turns it into a harnery-ready checkout: it installs deps, builds the Node dist/ (skipped when Bun is present), runs harn init to wire your project, and links the bins onto your PATH:

./scripts/setup.sh

Run it from the repo root. It auto-detects the project to wire (git toplevel of the CWD, else Harnery’s parent directory), and it’s idempotent. Flags: --project-root <dir>, --link-dir <dir> (default ~/.local/bin), --no-link, --adapter <id>. Reverse it with the mirror, ./scripts/teardown.sh (see Uninstall).

First-run check

harn doctor

This verifies the runtime + dependencies Harnery expects (Node version, optional Python, optional restic for backup, etc.). It exits 0 if everything’s wired and prints OS-specific install instructions for anything missing.

Bootstrap a project

harn init

Run once per project to create the .harnery/ coord root and wire the adapter hooks. Auto-wires all three adapters; pass --adapter claude-code (default), cursor, or codex. Idempotent and non-destructive: safe to re-run, and it preserves hooks you already have. See harn init for --dry-run and details.

Uninstall

Two layers, mirroring install. Unwire a project with harn deinit (on a terminal it asks before deleting .harnery/; keeps it by default). Remove the CLI with the hosted one-liner:

CLI (npm/bun)

harn deinit                                       # unwire a project (keeps .harnery/)
curl -fsSL https://harnery.com/uninstall.sh | bash   # remove the CLI itself

git clone

./scripts/teardown.sh   # mirror of setup.sh; also offers to remove state + the clone

From a clone, ./scripts/teardown.sh runs harn deinit, removes the PATH symlinks, and (on a terminal) asks whether to also delete this project’s .harnery/ history and the clone itself (both default to no). Pre-answer for unattended runs with --purge-state and --remove-clone; it also takes --link-dir, --keep-links, --project-root, --adapter, and --dry-run. See harn deinit for the surgical, hook-preserving details.

Next steps

• First run: quick tour of the most common commands
• Configuration: settings file format + precedence rules