Install

The default install on macOS, and the shortest path on any machine with Homebrew. One command, no Rust toolchain required.

Install Heddle

bash$ brew install --cask HeddleCo/tap/heddle

This taps HeddleCo/tap and installs the heddle cask onto your $PATH. Upgrades come through brew upgrade like anything else. It works on Linux too, though most Linux users reach for the install script or a prebuilt binary below.

The shortest path on any Unix machine without Homebrew. One command downloads the latest signed release binary from GitHub, verifies its SHA-256, and drops heddle into ~/.local/bin.

Install Heddle

bash$ curl -fsSL https://heddle.sh/install.sh | sh

Pin a release with HEDDLE_VERSION (for example HEDDLE_VERSION=v0.5.1) or change the target directory with HEDDLE_INSTALL_DIR. It is a plain POSIX script that needs only curl (or wget), tar, and a sha256 tool. Want to read it before you run? It lives at heddle.sh/install.sh.

A future upgrade over the install script: a tiny installer named heddleup that downloads signed release metadata, verifies the selected archive, and only then installs heddle. No remote shell is piped into your terminal.

Planned Linux bootstrap

bash$ curl -fSLO https://releases.heddle.dev/heddleup/latest/heddleup-x86_64-unknown-linux-gnu$ chmod +x ./heddleup && ./heddleup install heddle

If you have a Rust toolchain, this is one command from your shell.

Install heddle-cli from crates.io

bash$ cargo install heddle-cli

Cargo will resolve heddle-cli and its workspace siblings from crates.io, compile them, and place the heddle binary under ~/.cargo/bin.

The default build is the full first-run experience, with no feature flags to choose. You get Git-overlay mode (Heddle on top of an existing Git repo, the recommended on-ramp), native content-addressed mode, semantic diffing, and the mount worker, all on. See Git-overlay mode for what that gives you.

Want a slimmer binary? Opt out with --no-default-features and re-add only the modes you need, e.g. cargo install heddle-cli --no-default-features --features git-overlay.

For contributors. Clone the OSS workspace and install from a local path; useful when you're hacking on the CLI itself.

Install from a local clone

bash$ git clone https://github.com/HeddleCo/heddle.git$ cd heddle$ cargo install --path crates/cli --locked

Cargo will compile the full OSS workspace and drop the heddle binary into ~/.cargo/bin.

Every tagged release ships prebuilt artefacts for macOS (arm64, x86_64), Linux (x86_64, arm64), and Windows. Grab the latest from the Releases page, unpack it, and put heddle on your $PATH.

Verify the install

Whichever path you took, the same one-liner confirms Heddle is reachable.

Sanity check

bash$ heddle --versionheddle 0.5.1

If heddle --version errors with "command not found", your $PATH doesn't yet include the brew prefix (Homebrew), ~/.local/bin (install script), or ~/.cargo/bin (cargo). Open a fresh shell or add the relevant directory to $PATH.

Next

Move on to the Quickstart. Five minutes from a clean repo to a signed thread bridged back to Git.