Tooling Guide · CLI + MCP

Run the flow where you already work

H1VE Flow brings the workflow to the developer's home turf: the terminal (the nf CLI) and Claude Code (the MCP server). Both talk to the same panel API, authenticated by a personal token.

01 · Prerequisites

Before you start

Node.js 18.18+ installed (node --version). npm comes with it.
An account on H1VE Flow (app.h1ve.org).
A personal API token (PAT) — create one at app.h1ve.org/api-tokens. A PAT (nf_pat_…) authenticates as you: read and write. The service key is read-only. Keep the PAT safe — it's a secret, shown once.

02 · CLI — nf

Operate the flow from the terminal

The nf CLI drives the feature on your current branch — status, start, move, spec, done, blockers.

Install

npm i -g @h1veframework/clinf --version

Configure

# Two environment variables:export H1VE_API_URL="https://app.h1ve.org"export H1VE_API_KEY="nf_pat_..."      # your PAT nf health                              # tests the connection

Tip

Put the export lines in your ~/.zshrc / ~/.bashrc so you don't repeat them each session. "No snapshots registered" from nf health is a success response — it connected; the project just has no health metrics yet.

Commands

nf health: Latest technical-health snapshots for the project
nf status: State of the current branch's feature (stage, days active, blockers, sign-offs)
nf start [<n|id>]: Start an assigned feature: creates the branch feat/{you}/{slug} and records the slug
nf spec: Print the feature's spec (markdown)
nf move <stage>: Move the feature to another stage
nf done [--from <file>]: Submit the AI declaration (JSON) and move dev → pr
nf blocker "<desc>": Open a blocker on the feature (you become the owner)
nf connect …: Apply a credential to the local .env.local (never to the server) and register the connection inventory
nf serve: Run the local agent (127.0.0.1) so the panel's visual menu can apply credentials from the browser

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

Real example

nf start                                  # start the assigned feature (creates the branch)# ... work as usual (git, code, commits) ...nf status                                 # state at any timenf blocker "waiting on the Neon prod credential"nf done --from ai-declaration.json        # submit AI declaration + move dev → pr

03 · MCP Server — Claude Code

Plug the flow into your AI agent

The MCP server gives Claude Code direct access to the current branch's feature context — no copy-pasting SPECs. Plug it once; the tools show up in any project.

Install (plug into Claude Code)

claude mcp add h1ve -s user \  -e H1VE_API_URL=https://app.h1ve.org \  -e H1VE_API_KEY=nf_pat_... \  -- npx -y @h1veframework/mcp

-s user = available in all projects. For the current repo only, use -s local from inside it. No manual install — npx fetches the package on first run.

Confirm the connection

claude mcp list       # should list "h1ve: ✔ Connected"

Inside Claude Code, run /mcp — the h1ve server appears with 6 tools.

The 6 tools

get_current_feature: Branch feature state: stage, days active, blockers, sign-offs, ai-declaration
get_spec: The feature's spec (markdown)
move_feature_stage: Move the feature to another stage (rules validated on the server)
create_blocker: Open a blocker on the feature (you become the owner)
submit_ai_declaration: Submit the feature’s AI declaration (owner dev only)
start_feature: Start an assigned feature: records the slug and returns the git switch -c to create the branch

About the token

Read tools (get_current_feature, get_spec) work with a PAT or the service key. Write tools (move, blocker, ai-declaration, start) require a PAT — the service key returns SERVICE_CANNOT_WRITE.

04 · Troubleshooting

Common frictions

nf: command not found: Node not installed, or wrong terminal. Check node --version. On Windows, PowerShell may not expose the npm bin on PATH — use the VS Code terminal or reopen the shell after installing.
404 on install: npm propagation right after a publish. Wait a few minutes and retry.
NO_PROJECT: You belong to more than one project. Pass --project <name|id> on the CLI; the MCP resolves it from the branch context.
401 / 403: Wrong, missing, or unauthorized token. Ensure H1VE_API_KEY is a valid PAT (nf_pat_…). 403 SERVICE_CANNOT_WRITE = you used the read-only service key on a write action → use a PAT.

05 · Variable-name compatibility

Legacy names still work

Backward compatible

The current names are H1VE_API_URL and H1VE_API_KEY — use these. The legacy names NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY are still accepted for compatibility — if you already configured with them, you don't need to change anything. We recommend H1VE_* for new setups.