CLI, SSH and MCP

Install the CLI

Install the heaven program on a Mac or Linux computer, keep it up to date, or remove it.

Overview

The heaven program runs Heaven's commands from a terminal (CLI and SSH) and serves them to your agents (MCP). It's one file, built for macOS and Linux on Intel/AMD (amd64) and ARM (arm64) processors. Installing it doesn't need administrator access.

Terminal

curl -fsSL https://heaven.dev/install | sh

The script picks the program for your computer from https://heaven.dev/cli, checks it against the published SHA256SUMS, and puts it in ~/.local/bin/heaven. A download that fails the check installs nothing. You can read the script before you run it.

Install

macOS

macOS has everything the script uses: curl, ssh and shasum. It works on Apple silicon and Intel Macs.

Terminal

curl -fsSL https://heaven.dev/install | sh

If ~/.local/bin isn't on your PATH yet, the script says so. With zsh, the default shell on macOS, add it and open a new terminal:

Terminal

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Linux

The script needs ssh (OpenSSH), curl or wget, and sha256sum, which most distributions have. If ssh is missing, install OpenSSH's client first, for example with sudo apt install openssh-client. On Windows, run these steps in WSL.

Terminal

curl -fsSL https://heaven.dev/install | sh

If ~/.local/bin isn't on your PATH yet, the script says so. With bash, add it and open a new terminal:

Terminal

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Download it yourself

Download the file for your computer and its checksums, check it, and put it on your PATH as heaven:

Computer	File
Mac with Apple silicon	`heaven-darwin-arm64`
Mac with an Intel processor	`heaven-darwin-amd64`
Linux on Intel or AMD	`heaven-linux-amd64`
Linux on ARM	`heaven-linux-arm64`

Linux on Intel or AMD

curl -fsSLO https://heaven.dev/cli/heaven-linux-amd64 &&
curl -fsSLO https://heaven.dev/cli/SHA256SUMS &&
sha256sum --check --ignore-missing SHA256SUMS &&
chmod +x heaven-linux-amd64 &&
mkdir -p ~/.local/bin && mv heaven-linux-amd64 ~/.local/bin/heaven

Each step runs only when the one before it worked, so a file that fails its check is never installed. Use your own file's name instead, and on a Mac check it with shasum -a 256 --check --ignore-missing SHA256SUMS. https://heaven.dev/cli/VERSION gives the version of these files.

To install it somewhere else, set HEAVEN_INSTALL_DIR for the script: curl -fsSL https://heaven.dev/install | HEAVEN_INSTALL_DIR=/usr/local/bin sh.

Sign in and connect your agents

Check that it runs, sign in once, and add Heaven's MCP server to the agents on your computer:

Terminal

heaven version
heaven login
heaven mcp install

heaven login opens a link in your browser to approve the sign-in. heaven mcp install adds the server to whichever of Claude Code, Codex, Gemini CLI, Claude Desktop, Cursor and VS Code you have.

Update

The program never updates itself. When Heaven publishes a version other than yours, a command you run at a terminal says so, at most once a day. Then run:

Terminal

heaven update

It downloads the published version, checks it as the script does, and replaces the program in place. Running the install script again does the same.

Uninstall

Sign out first: heaven logout revokes the program's sign-in and removes the SSH key it added to your account. Then remove the program and what it keeps:

Terminal

heaven logout
rm ~/.local/bin/heaven
rm -rf ~/.config/heaven

Agents you connected with heaven mcp install keep a server named heaven in their settings. Remove it there, for example with claude mcp remove --scope user heaven.