README
¶
hadron-cli
hadron is the command-line interface to the Hadron
AI-memory platform, for humans working in a terminal and AI agents
shelling out to it.
Status
Full v1 command surface implemented: auth login|logout|whoami|status,
memory ls|get|set|rm|clone|export, node ls|get|add|update|rm,
spec ls|get|describe|register|find|new|lint|supersede|import,
app ls|install|uninstall|use, config get|set|list, api (raw
GraphQL escape hatch), version, completion, agentic-usage.
Specs follow a legal-code citation scheme — flat (<module>:<feature>:<rule>)
or product-rooted (<product>:<module>:<feature>:<rule>) for a multi-product
corpus — with a general-provisions contract at every tier (feature :00,
module :000, product :gen). See
docs/how-to/maintain-product-specs.md.
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 against checksums.txt, and put hadron on your PATH.
Go
go install github.com/hadron-memory/hadron-cli/cmd/hadron@latest
(go install builds without the version stamp — hadron version reports dev.)
From source
make build # produces bin/hadron, version-stamped
Requires Go (see go.mod for the version).
Quick start
hadron auth login # browser OAuth; token stored in OS keychain
hadron auth whoami
hadron memory ls --json
hadron api 'query { me { id email } }'
For CI/scripting, set HADRON_TOKEN or pipe a personal access token
to hadron auth login --with-token.
For AI agents
Run hadron agentic-usage — it prints the full output contract,
stable exit codes, and recipes in one document. Every command
supports --json with stable field names.
Claude Code plugin
This repo is also a Claude Code plugin marketplace. In Claude Code:
/plugin marketplace add hadron-memory/hadron-cli
/plugin install hadron-cli@hadron
The hadron-cli plugin ships a use-hadron-cli skill that teaches
the agent the CLI contract (auth checks, --json, --yes on
destructive commands, fully-qualified node URNs) and defers to
hadron agentic-usage as the runtime source of truth.
Development
make build # build with version stamp
make test # go test ./...
make lint # golangci-lint run
make generate # regenerate genqlient code from schema/schema.graphql
make schema # refresh schema snapshot from ../hadron-server, then generate
The GraphQL schema snapshot at schema/schema.graphql is exported
from hadron-server (pnpm schema:export there) and committed here;
typed operations live in internal/api/queries/*.graphql and are
compiled by genqlient. CI fails
if generated code drifts from the committed schema.
Architecture notes
- Auth (v1): OAuth authorization-code + PKCE with a loopback
redirect on 127.0.0.1. The server matches redirect URIs exactly, so
each login binds the port first and registers a fresh public client
via dynamic client registration. The resulting token is a
long-lived
hdr_user_*personal access token (no refresh tokens in v1). Stored in the OS keychain, falling back to~/.config/hadron/auth.json(0600). A device-flow strategy can slot in behindinternal/auth.Strategyonce the server supports RFC 8628. - Output: commands marshal explicit DTOs, never generated
GraphQL structs, so
--jsonshapes stay stable across schema regenerations. - Exit codes are documented contract — see
hadron agentic-usage.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
hadron
command
|
|
|
internal
|
|
|
api
Package api wraps the Hadron GraphQL endpoint: a genqlient client for typed operations, a raw escape hatch for `hadron api`, and the mapping from transport/GraphQL errors to exit codes.
|
Package api wraps the Hadron GraphQL endpoint: a genqlient client for typed operations, a raw escape hatch for `hadron api`, and the mapping from transport/GraphQL errors to exit codes. |
|
auth
Package auth implements `hadron auth login` flows against the Hadron OAuth endpoints (spec 025: authorization-code + PKCE, public client via dynamic client registration).
|
Package auth implements `hadron auth login` flows against the Hadron OAuth endpoints (spec 025: authorization-code + PKCE, public client via dynamic client registration). |
|
auth/store
Package store persists the Hadron access token, preferring the OS keychain and falling back to a 0600 file when no keychain is available (CI containers, headless boxes).
|
Package store persists the Hadron access token, preferring the OS keychain and falling back to a 0600 file when no keychain is available (CI containers, headless boxes). |
|
build
Package build holds version metadata stamped at build time via -ldflags (see Makefile and .goreleaser.yaml).
|
Package build holds version metadata stamped at build time via -ldflags (see Makefile and .goreleaser.yaml). |
|
cmd
Package cmd assembles the hadron command tree and owns the single error → exit-code → rendering path.
|
Package cmd assembles the hadron command tree and owns the single error → exit-code → rendering path. |
|
cmd/agentic
Package agentic implements `hadron agentic-usage` (D8): a single document an agent can read to learn the CLI.
|
Package agentic implements `hadron agentic-usage` (D8): a single document an agent can read to learn the CLI. |
|
cmd/aiconfig
Package aiconfig implements `hadron ai-config ...` — the AI service config surface.
|
Package aiconfig implements `hadron ai-config ...` — the AI service config surface. |
|
cmd/apicmd
Package apicmd implements `hadron api`, the raw GraphQL escape hatch (same role as `gh api`).
|
Package apicmd implements `hadron api`, the raw GraphQL escape hatch (same role as `gh api`). |
|
cmd/app
Package app implements `hadron app ...`.
|
Package app implements `hadron app ...`. |
|
cmd/auth
Package auth implements `hadron auth ...`.
|
Package auth implements `hadron auth ...`. |
|
cmd/configcmd
Package configcmd implements `hadron config ...`.
|
Package configcmd implements `hadron config ...`. |
|
cmd/edge
Package edge implements `hadron edge ...` — directed, labeled connections between two nodes.
|
Package edge implements `hadron edge ...` — directed, labeled connections between two nodes. |
|
cmd/memory
Package memory implements `hadron memory ...`.
|
Package memory implements `hadron memory ...`. |
|
cmd/node
Package node implements `hadron node ...`.
|
Package node implements `hadron node ...`. |
|
cmd/spec
Package spec implements `hadron spec ...` — an opinionated layer over the generic node/edge commands for maintaining product-spec nodes that follow the loc-as-citation convention: a spec's loc IS its citation number, <module>:<feature>:<rule>:<flow> (e.g.
|
Package spec implements `hadron spec ...` — an opinionated layer over the generic node/edge commands for maintaining product-spec nodes that follow the loc-as-citation convention: a spec's loc IS its citation number, <module>:<feature>:<rule>:<flow> (e.g. |
|
cmd/version
Package version implements `hadron version`.
|
Package version implements `hadron version`. |
|
cmdutil
Package cmdutil provides the Factory injected into every command: lazily-resolved config, token store, and API client, plus the values of the persistent --json/--server/--app flags.
|
Package cmdutil provides the Factory injected into every command: lazily-resolved config, token store, and API client, plus the values of the persistent --json/--server/--app flags. |
|
config
Package config reads and writes ~/.config/hadron/config.toml.
|
Package config reads and writes ~/.config/hadron/config.toml. |
|
exitcode
Package exitcode defines the hadron CLI's stable, documented exit codes.
|
Package exitcode defines the hadron CLI's stable, documented exit codes. |
|
output
Package output renders command results as human-readable text or JSON.
|
Package output renders command results as human-readable text or JSON. |