Skip to content

Install the hadron CLI

CLI onlyBeginner~5 min

hadron is the command-line interface to the Hadron platform — for humans working in a terminal and for AI agents shelling out to it. This guide gets it installed and authenticated. For the full command surface and output contract, see the hadron CLI reference.

Install

Homebrew (macOS)

brew tap hadron-memory/tap
brew install --cask hadron

Release archives (macOS, Linux, Windows)

Download the archive for your platform from the latest release, verify it against checksums.txt, and put the hadron binary on your PATH.

Go

go install github.com/hadron-memory/hadron-cli/cmd/hadron@latest

Note

go install builds without the release version stamp, so hadron version reports dev. Functionality is identical.

Linux / Debian (Go from official tarball)

On Debian and other Linux distributions, the system Go package can lag behind what @latest needs. For a fresh Linux host, install the official Go toolchain from the tarball:

# 1. Download and install the official Go toolchain (latest)
VER=$(curl -fsSL "https://go.dev/VERSION?m=text" | head -1)   # e.g. go1.26.4
curl -fsSL -o /tmp/go.tgz "https://go.dev/dl/${VER}.linux-amd64.tar.gz"
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf /tmp/go.tgz

# 2. Add Go and the install target directory to your PATH
export PATH=/usr/local/go/bin:$HOME/go/bin:$PATH   # GOPATH/bin defaults to ~/go/bin
# Persist for future shells by adding the above to ~/.bashrc, ~/.zshrc, etc.

# 3. Install the CLI
go install github.com/hadron-memory/hadron-cli/cmd/hadron@latest

# 4. (Optional) Make it available system-wide
sudo ln -sf "$HOME/go/bin/hadron" /usr/local/bin/hadron

Verify: 

hadron version

Sign in

Interactive OAuth (browser-based)

Opens your browser for OAuth; the token is stored in your OS keychain:

hadron auth login
hadron auth whoami

Headless hosts (SSH / remote servers): The OAuth callback redirects to 127.0.0.1 on your client machine, but the CLI listener is on the host's 127.0.0.1, so the callback never reaches the CLI. Two workarounds:

  1. Deliver the callback manually. The browser shows a redirect URL like http://127.0.0.1:53284/callback?code=...&state=.... Copy that URL and paste it into curl on the host: 

    curl "http://127.0.0.1:53284/callback?code=...&state=..."
    The CLI receives the code and completes the flow.

  2. Skip the browser entirely. Mint a token on your local machine and pipe it to the remote: 

    # On your local machine:
hadron auth token create --label remote-work
# Copy the printed hdr_user_* token, then on the remote:
echo "hdr_user_..." | hadron auth login --with-token

Personal access tokens (CI, scripts, agents)

For non-interactive contexts, use a personal access token. Mint one from the CLI once you're signed in — hadron auth token create — or in the portal (see Manage your API keys); the portal is optional:

hadron auth token create --label ci-deploy   # mint; prints the raw key ONCE
export HADRON_TOKEN=hdr_user_...              # env var, overrides stored tokens
# or store it once:
echo "$TOKEN" | hadron auth login --with-token

Note on headless hosts: There is no OS keychain on a headless server, so stored tokens live in ~/.config/hadron/auth.json instead. The CLI falls back automatically — nothing to configure.

Verify

hadron auth status        # exit 0 = signed in
hadron memory ls --json   # list the memories you can see

The CLI talks to https://srv.hadronmemory.com by default. For a self-hosted server:

hadron config set server https://your-server.example.com

For AI agents

Two options once the binary is installed:

  • Tell the agent to run hadron agentic-usage — the CLI prints its own complete agent contract (stable exit codes, --json output rules, recipes).
  • In Claude Code, install the skill plugin:
/plugin marketplace add hadron-memory/hadron-cli
/plugin install hadron-cli@hadron

Next steps