Guia de Ferramentas · CLI + MCP

Rode o fluxo onde você já trabalha

O H1VE Flow traz o workflow para o território do desenvolvedor: o terminal (a CLI nf) e o Claude Code (o MCP server). Os dois falam com a mesma API do painel, autenticados por um token pessoal.

01 · Pré-requisitos

Antes de começar

Node.js 18.18+ instalado (node --version). O npm vem junto.
Uma conta no H1VE Flow (app.h1ve.org).
Um token pessoal de API (PAT) — crie um em app.h1ve.org/api-tokens. Um PAT (nf_pat_…) autentica como você: leitura e escrita. A service key é somente leitura. Guarde o PAT com cuidado — é um segredo, exibido uma única vez.

02 · CLI — nf

Opere o fluxo pelo terminal

A CLI nf conduz a feature na sua branch atual — status, start, move, spec, done, blockers.

Instalar

npm i -g @h1veframework/clinf --version

Configurar

# Duas variáveis de ambiente:export H1VE_API_URL="https://app.h1ve.org"export H1VE_API_KEY="nf_pat_..."      # seu PAT nf health                              # testa a conexão

Dica

Coloque as linhas export no seu ~/.zshrc / ~/.bashrc para não repeti-las a cada sessão. "No snapshots registered" do nf health é uma resposta de sucesso — ele conectou; o projeto só ainda não tem métricas de saúde.

Comandos

nf health: Últimos snapshots de saúde técnica do projeto
nf status: Estado da feature da branch atual (estágio, dias ativos, blockers, sign-offs)
nf start [<n|id>]: Inicia uma feature atribuída: cria a branch feat/{você}/{slug} e registra o slug
nf spec: Imprime a spec da feature (markdown)
nf move <stage>: Move a feature para outro estágio
nf done [--from <file>]: Submete a AI declaration (JSON) e move dev → pr
nf blocker "<desc>": Abre um blocker na feature (você vira o dono)
nf connect …: Aplica uma credencial ao local .env.local (nunca ao servidor) e registra o inventário de conexões
nf serve: Roda o agente local (127.0.0.1) para o menu visual do painel aplicar credenciais pelo navegador

Flags úteis: --json (saída crua para scripts) · --project <name|id> (se você pertence a mais de um projeto) · -h (ajuda completa).

Exemplo real

nf start                                  # inicia a feature atribuída (cria a branch)# ... trabalhe normalmente (git, código, commits) ...nf status                                 # estado a qualquer momentonf blocker "aguardando a credencial de prod do Neon"nf done --from ai-declaration.json        # submete a AI declaration + move dev → pr

03 · MCP Server — Claude Code

Plugue o fluxo no seu agente de IA

O MCP server dá ao Claude Code acesso direto ao contexto da feature da branch atual — sem copiar e colar SPECs. Plugue uma vez; as tools aparecem em qualquer projeto.

Instalar (plugar no 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 = disponível em todos os projetos. Só para o repo atual, use -s local de dentro dele. Sem install manual — o npx busca o pacote na primeira execução.

Confirmar a conexão

claude mcp list       # deve listar "h1ve: ✔ Connected"

Dentro do Claude Code, rode /mcp — o server h1ve aparece com 6 tools.

As 6 tools

get_current_feature: Estado da feature da branch: estágio, dias ativos, blockers, sign-offs, ai-declaration
get_spec: A spec da feature (markdown)
move_feature_stage: Move a feature para outro estágio (regras validadas no servidor)
create_blocker: Abre um blocker na feature (você vira o dono)
submit_ai_declaration: Submete a AI declaration da feature (só o dev dono)
start_feature: Inicia uma feature atribuída: registra o slug e devolve o git switch -c para criar a branch

Sobre o token

Tools de leitura (get_current_feature, get_spec) funcionam com um PAT ou com a service key. Tools de escrita (move, blocker, ai-declaration, start) exigem um PAT — a service key retorna SERVICE_CANNOT_WRITE.

04 · Solução de problemas

Fricções comuns

nf: command not found: Node não instalado, ou terminal errado. Confira node --version. No Windows, o PowerShell pode não expor o bin do npm no PATH — use o terminal do VS Code ou reabra o shell após instalar.
404 no install: Propagação do npm logo após uma publicação. Espere alguns minutos e tente de novo.
NO_PROJECT: Você pertence a mais de um projeto. Passe --project <name|id> na CLI; o MCP resolve pelo contexto da branch.
401 / 403: Token errado, ausente ou não autorizado. Garanta que H1VE_API_KEY é um PAT válido (nf_pat_…). 403 SERVICE_CANNOT_WRITE = você usou a service key (somente leitura) numa ação de escrita → use um PAT.

05 · Compatibilidade de nomes de variável

Os nomes legados ainda funcionam

Retrocompatível

Os nomes atuais são H1VE_API_URL e H1VE_API_KEY — use estes. Os nomes legados NEXUS_FLOW_API_URL / NEXUS_FLOW_API_KEY ainda são aceitos por compatibilidade — se você já configurou com eles, não precisa mudar nada. Recomendamos H1VE_* para novas configurações.