@h1veframework/cli · h1ve

The command-line companion for H1VE — the governance & memory layer for teams building with AI.

Your team ships with AI (Claude Code, Cursor, Copilot). As the codebase grows, the AI and your teammates start losing context and drifting from decisions you already made. H1VE keeps every feature aligned — a shared, eternal project memory plus an anti-drift engine that checks each change against what's been decided. h1ve drives that workflow straight from your terminal.

Part of the H1VE toolchain, alongside the MCP server for Claude Code / Cursor.

→ h1ve.org · app.h1ve.org

Quickstart (zero paste)

npm i -g @h1veframework/cli
h1ve login     # opens your browser → you click Authorize → done
h1ve status    # state of the current branch's feature

h1ve login stores the credential locally (~/.config/h1ve/credentials.json, 600) — the MCP server reads the same one, so one login sets up both. The project auto-resolves from your git remote, so there's nothing to paste and no H1VE_PROJECT_ID to set. h1ve logout removes it.

The legacy nf command still works as an alias — every h1ve <cmd> below can be run as nf <cmd>.

h1ve health saying "no snapshots yet" is success (you're connected; the project just has no metrics yet).

Commands

| Command | What it does | |---|---| | h1ve login / h1ve logout | Authorize in the browser and store the credential locally / remove it | | h1ve status | State of the current branch's feature (stage, days active, blockers, sign-offs) | | h1ve start [<#\|id>] [--slug <s>] | Start an assigned feature: create the feat/{you}/{slug} branch and record the slug | | h1ve spec | Print the feature's spec (markdown) | | h1ve move <stage> [--note] | Move the feature to another stage | | h1ve done [--from <file>] [--no-move] | Submit the AI declaration (JSON) and move dev → pr | | h1ve blocker "<desc>" | Open a blocker on the feature (you become its owner) | | h1ve health | Latest technical-health snapshots for the project | | h1ve connect --kind <k> --label <l> --env KEY=VAL | Write a credential to your local .env.local and register the inventory (never sent to the server) | | h1ve serve [--port 7391] | Run the local agent (127.0.0.1) so the dashboard can apply credentials from the browser |

Flags: --json (raw output for scripts) · --project <name\|id> (if you belong to more than one project) · -h.

Example

h1ve start                                    # start your assigned feature (creates the branch)
# ... work: git, code, commits ...
h1ve status                                   # check state anytime
h1ve blocker "waiting on the Neon credential" # blocked? open a blocker
h1ve done --from ai-declaration.json          # submit the AI declaration + move dev → pr

CI / headless (env vars)

No browser? Configure by env (takes precedence over h1ve login):

export H1VE_API_URL="https://app.h1ve.org"   # optional (this is the default)
export H1VE_API_KEY="nf_pat_..."             # a PAT from app.h1ve.org/api-tokens
# export H1VE_PROJECT_ID="..."               # OPTIONAL — the CLI resolves the project from the repo

Troubleshooting

| Symptom | Fix | |---|---| | h1ve: command not found | Node missing or wrong terminal. Check node --version. On Windows, reopen the shell or use the VS Code terminal. | | 404 on install | npm propagation right after a publish — wait a few minutes. | | NO_PROJECT | You belong to more than one project — pass --project <name\|id>. | | 401 / 403 | Wrong/missing token. Make sure H1VE_API_KEY is a PAT (nf_pat_…). 403 SERVICE_CANNOT_WRITE = a read-only service key used on a write → use a PAT. |

Requires Node.js 18.18+. The legacy nf command and env names NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY are still accepted.

MIT · built with H1VE, by H1VE 🐝