Ir al contenido
HQ Fabric

CLI hqf

Los comandos de hqf, el CLI y daemon de HQ Fabric, con sus flags, su configuración y sus códigos de salida.

hqf es dos cosas en un binario. Es el CLI con el que conectas una máquina a HQ Fabric, y es el daemon que, en esa máquina, reclama tareas y ejecuta a los agentes. Dentro del worktree de una tarea, el agente también lo usa: comenta, pregunta o se bloquea con hqf agent.

Esta referencia sale del código, no de la ayuda. Donde la ayuda se queda corta, lo dice.

Instalar el binario

Desde el repo, make cli compila bin/hqf. Para otra máquina, make dist compila hqf para Linux y macOS, en amd64 y arm64, dentro de bin/dist.

make cli
./bin/hqf version
hqf 0.1.0

Hoy la versión siempre es 0.1.0: ningún build la fija.

Lo común a todos los comandos

TemaComportamiento
Configuración$HQF_HOME/config.json. Sin HQF_HOME, ~/.hqfabric/config.json. El directorio se crea con permisos 0700 y el fichero con 0600
IdiomaInglés si HQF_LANG seguido de LANG empieza por en; si no, español. LC_ALL no cuenta
Flags y argumentosLos flags pueden ir después de los argumentos. Un flag booleano delante de un argumento se come ese argumento: pon los booleanos al final
Sin argumentosImprime la ayuda y sale con 2
Comando desconocidocomando desconocido: <x>, la ayuda y sale con 2
Error✘ <error> en stderr y sale con 1

Comandos para ti

hqf setup

Inicia sesión, elige los workspaces que atiende esta máquina y arranca el daemon. Es lo primero que corres.

hqf setup --server http://127.0.0.1:8080 --app http://127.0.0.1:3000 --name mi-portatil
FlagPor defectoQué hace
--serverel server_url guardado (http://localhost:8080)URL de la API
--appel app_url guardado (http://localhost:3000)URL de la web, para los enlaces que imprime
--nameel nombre de la máquinaNombre de este runtime en la web
--no-daemonfalseNo arranca el daemon al terminar

Lo que hace, en orden:

  1. Si no hay sesión guardada, o la que hay no vale, te pide el correo y el código (como hqf login).
  2. Lista tus workspaces. Con uno, lo elige solo. Con varios, te pregunta (1,3; vacío elige todos). Sin ninguno, falla: crea el primero en la web.
  3. Detecta los CLIs de agentes de la máquina y los imprime.
  4. Arranca el daemon (como hqf daemon start), salvo con --no-daemon.
→ Servidor: http://127.0.0.1:8080
Correo: ℹ El servidor no tiene correo configurado: el código aparece en los logs del backend.
Código: ✔ Sesión iniciada como ana (ana@hqfabric.example)
  ✔ Acme
  CLIs de agentes detectados:
    ✔ Claude Code          2.1.0      /usr/local/bin/claude
✔ Daemon iniciado (pid 6088). Logs: /Users/ana/.hqfabric/daemon.log

✔ Listo. Abre http://127.0.0.1:3000, crea un agente y asígnale un issue.

hqf login

Inicia sesión con un código por correo y guarda un token en config.json.

FlagPor defectoQué hace
--serverel guardadoURL de la API
--appel guardadoURL de la web
--emaillo pide (propone el guardado)Tu correo
--codelo pideEl código de 6 dígitos

El token que guarda es un token personal de alcance runtime, llamado hqf@<máquina>. Sólo sirve para registrar runtimes y leer tus workspaces: no puede aprobar nada ni tocar issues.

hqf logout

Vacía el token de sesión y el token de runtime de cada workspace en config.json. No avisa al servidor y no para el daemon: si el daemon sigue corriendo, puede volver a escribir sus tokens. Para el daemon antes (hqf daemon stop).

hqf config

hqf config show
hqf config set max_parallel 2

show imprime la configuración con los valores por defecto ya aplicados, sin el token. set cambia una clave; las siete que acepta están en Claves de configuración. Si el daemon corre, reinícialo para que la lea: la carga al arrancar.

hqf workspaces

hqf workspaces
hqf workspaces add acme
hqf workspaces remove acme

Sin argumentos, pide al servidor tus workspaces y marca los que atiende esta máquina. add y remove sólo cambian config.json, sin preguntar al servidor. El alias corto es hqf ws.

hqf repo

hqf repo link api ~/src/api --workspace acme
hqf repo list

link asocia un proyecto (su slug) a una carpeta de esta máquina, que tiene que ser un repo de git. Con un solo workspace en la configuración, --workspace sobra. list imprime los repos asociados.

Si el daemon ya corre, reinícialo después de link: no ve la carpeta hasta que vuelve a arrancar. Desde la web (Runtimes → Configurar → Vincular) el cambio llega al daemon sin reiniciar.

Un proyecto sin repo asociado y sin repo remoto no se queda sin trabajar. El daemon le crea un repo de prueba en $HQF_HOME/repos/<workspace>/_scratch-<proyecto>, y ahí quedan las ramas y las fusiones.

hqf daemon

hqf daemon start
hqf daemon status
hqf daemon logs -f
hqf daemon stop
SubcomandoQué hace
status (o nada)Dice si corre, contra qué servidor, el runtime de cada workspace y los CLIs detectados
startLanza hqf daemon run en segundo plano, con la salida en $HQF_HOME/daemon.log, y guarda el PID en daemon.pid
stopManda SIGTERM al PID de daemon.pid y lo borra. No espera a que termine
runEl daemon en primer plano. Es lo que lanzan start, el servicio systemd de una VPS y el runtime «Usar esta máquina»
logsLos últimos 32 KiB del log. Con -f o --follow, lo sigue

start imprime «Daemon iniciado» aunque el proceso muera enseguida. Si algo falla, mira hqf daemon logs.

El daemon atiende cada workspace por separado. Se registra como runtime, late cada 20 s, reclama tareas cada 15 s mientras tenga cupo (max_parallel por workspace) y mantiene un WebSocket con el servidor para las terminales y los cambios de configuración que llegan de la web. Necesita git 2.45.1 o más nuevo.

hqf agents

Detecta los CLIs de agentes de esta máquina: busca cada binario en el PATH y ejecuta <binario> --version. Reconoce claude, codex, cursor-agent, gemini, copilot, opencode, qwen, kimi, amp y goose. hqf agents detect hace lo mismo.

hqf ping

hqf ping http://127.0.0.1:8080

Comprueba que esta máquina llega al servidor: pide /api/config y espera una versión.

Servidor HQ Fabric 0.1.0 accesible en http://127.0.0.1:8080

hqf harness

hqf harness list
hqf harness install claude-code
hqf harness install --upgrade codex
hqf harness login claude-code

Instala los CLIs de agentes sin sudo y abre su inicio de sesión. Los identificadores son claude-code, codex, cursor, gemini, copilot, opencode, qwen, kimi, amp y goose.

SubcomandoQué hace
list (o ls, o nada)Tabla con cada CLI, su versión y si tiene sesión
install <id>Instala la versión fijada. Los de npm van a ~/.npm-global; si no hay npm, descarga Node.js 22 en ~/.local/node y comprueba su SHA-256. Cursor, Kimi y Goose usan su script de instalación
install --upgrade <id> (o -u)Instala la última versión
login <id>Ejecuta el inicio de sesión del CLI de forma interactiva

Los botones de Runtimes → Harnesses en la web escriben estos mismos comandos en la terminal del runtime.

hqf version y hqf help

hqf version (también --version o -v) imprime la versión. hqf help (también -h o --help) imprime la ayuda.

Comandos del agente

El daemon lanza al agente con hqf en el PATH y estas variables: HQF_SERVER_URL, HQF_TASK_ID, HQF_TASK_TOKEN, HQF_WORKTREE, HQF_ISSUE_KEY y HQF_LOCALE. Sin ellas, hqf agent falla con «sólo funciona dentro de una tarea». El token de la tarea sólo sirve para su propia tarea.

ComandoQué hace
hqf agent comment "<texto>"Comenta en el issue. El servidor redacta los secretos
hqf agent block "<motivo>"Marca la tarea como bloqueada con ese motivo, y lo escribe en .hqf/BLOCKED.md
hqf agent remember [--section s] [--scope project|agent|workspace] "<lección>"Guarda una lección en la memoria del equipo (12 caracteres como mínimo)
hqf agent issue "<título>" ["<descripción>"]Crea un issue nuevo en el backlog para algo que no es de esta tarea
hqf agent ask [--domain d] "<pregunta>" ["<pregunta>" …]Deja preguntas libres para una persona (de 1 a 10) y la tarea espera las respuestas
hqf agent ask --question "<pregunta>" --options "a|b" [--default a --timeout 30m] [--role r]Pregunta con opciones (de 2 a 8). Con --default y --timeout, si nadie responde a tiempo, vale la opción por defecto. --role limita quién responde: product_owner, engineer, code_owner o context_owner
hqf agent checkpoint --step "…" [--next "…"] [--blockers "…"]Guarda su estado (2 KB entre los tres campos) y muestra el anterior
hqf agent subtask --title "…" --prompt "…"Crea un issue hijo con los permisos del padre como tope

hqf skills get [<tema>] [--full] [--json] imprime la guía de hqf que lleva el binario, sin red. Los temas son protocolo, checkpoint, ask, block, remember, issue, subtask y sdlc.

hqf git diff|log|show [args] es un git de sólo lectura para el agente de revisión, que no tiene shell. Rechaza las opciones que escriben o ejecutan algo (--output, --ext-diff, -c y otras).

Comandos internos

Los lanza el servidor, el daemon o Claude Code. No los necesitas a mano, y no salen en la ayuda.

ComandoQuién lo lanzaPara qué
hqf egress-proxy [--listen :3128] [--allow host:port,…]El servidor, en el contenedor hqf-egress de un runtime DockerProxy de salida: deja internet y bloquea la red local, loopback y los metadatos de la nube
hqf hook <pre-tool-use|post-edit|stop|notification> --rules <fichero>Claude Code, desde la configuración que deja el daemonAplica las reglas de la tarea a cada herramienta y al cierre
hqf mcp serve --task <id>Claude Code en autonomía supervisedEl servidor MCP con la herramienta de permisos
(askpass)git, desde el daemonCon HQF_ASKPASS_SOCK en el entorno, hqf responde a git como GIT_ASKPASS

Claves de configuración

hqf config set <clave> <valor> acepta estas siete. Desde la web (Runtimes → Configurar) se cambian runtime_name, max_parallel y task_timeout, con límites más estrictos que los del CLI.

ClavePor defectoValidación en el CLIDesde la web
server_urlhttp://localhost:8080ningunano
app_urlhttp://localhost:3000ningunano
runtime_nameel nombre de la máquinaningunasí, de 1 a 64 caracteres
max_parallel3un entero ≥ 1sí, de 1 a 32
task_timeout2huna duración de Go (30m, 2h)sí, de 1 min a 72 h
worktrees_dir$HQF_HOME/worktreesningunano
repos_dir$HQF_HOME/reposningunano

max_parallel cuenta por workspace: con dos workspaces y max_parallel 3, la máquina corre hasta seis tareas.

config.json

{
  "server_url": "http://localhost:8080",
  "app_url": "http://localhost:3000",
  "token": "<token de API, alcance runtime>",
  "email": "ana@hqfabric.example",
  "runtime_name": "mi-portatil",
  "max_parallel": 3,
  "worktrees_dir": "/Users/ana/.hqfabric/worktrees",
  "repos_dir": "/Users/ana/.hqfabric/repos",
  "task_timeout": "2h",
  "env": { "ANTHROPIC_API_KEY": "…" },
  "workspaces": [
    {
      "slug": "acme",
      "id": "<uuid del workspace>",
      "runtime_id": "<uuid del runtime>",
      "runtime_token": "<token del runtime>",
      "repos": { "api": "/Users/ana/src/api" }
    }
  ]
}

env guarda las claves de API de los CLIs que pones desde la web (Runtimes → Harnesses). Sólo acepta ANTHROPIC_API_KEY, CURSOR_API_KEY, GEMINI_API_KEY, COPILOT_GITHUB_TOKEN y AMP_API_KEY.

Ficheros

FicheroQué es
$HQF_HOME/config.jsonLa configuración
$HQF_HOME/daemon.pidEl PID del daemon
$HQF_HOME/daemon.logEl log del daemon. No rota
$HQF_HOME/worktrees/Un worktree por tarea
$HQF_HOME/repos/Los clones que hace el daemon y los repos de prueba de los proyectos sin repo
$HQF_HOME/state/El estado de las tareas en curso
~/.hqfabric/harness-auth.jsonDónde guarda su sesión cada CLI, aprendido en hqf harness login. Siempre bajo $HOME, aunque fijes HQF_HOME

Variables de entorno

VariablePara quéPor defecto
HQF_HOMELa carpeta de la configuración y del trabajo del daemon~/.hqfabric
HQF_LANGEl idioma de los mensajes (en para inglés)se mira con LANG
HQF_HIBERNATE_AFTERTras cuánto tiempo sin actividad se hiberna una terminal interactiva de Claude Code30m
HQF_PORT_RANGEEl rango del que sale HQF_PORT para cada worktree41000-41999
HQF_WORKTREE_GC_INTERVALCada cuánto pasa el recolector de worktrees1h
SHELLEl shell de las terminales/bin/bash
HQF_AGENT_ENV_ALLOWNombres exactos de variables del entorno del daemon que pasan también a los agentes y a la verificación, separados por comas. Ver abajovacía

Qué entorno reciben los agentes

El agente no hereda el entorno del daemon. Recibe una lista mínima: PATH, HOME, USER, SHELL, LANG y LC_*, TZ, TMPDIR, TERM, XDG_*, el proxy y los certificados (HTTPS_PROXY, NO_PROXY, SSL_CERT_FILE, NODE_EXTRA_CA_CERTS…), el perfil de los CLIs (CLAUDE_CONFIG_DIR, CODEX_HOME) y las claves que guardas en el runtime desde la web (ANTHROPIC_API_KEY, CURSOR_API_KEY, GEMINI_API_KEY, COPILOT_GITHUB_TOKEN, AMP_API_KEY).

Para pasar otra variable, nómbrala en HQF_AGENT_ENV_ALLOW al arrancar el daemon:

HQF_AGENT_ENV_ALLOW=OPENAI_API_KEY,DOCKER_HOST hqf daemon start

Lo que pongas en HQF_AGENT_ENV_ALLOW llega también a la verificación, al pre-commit, al verifier, al revisor y a los pasos de worktree.yaml, que ejecutan código del repo. No nombres ahí nada que no quieras dar a ese código.

Los secretos del servidor (JWT_SECRET, SECRETS_KEY, DATABASE_URL, POSTGRES_PASSWORD, RESEND_API_KEY) y los tokens de HQ Fabric no pasan nunca, aunque los nombres. Si un CLI falla sin sesión, el error de la tarea dice cómo iniciarla y qué variable con pinta de credencial había en el entorno del daemon sin pasar.

Un valor inválido en las variables de duración o de rango se ignora y vale el de por defecto.

Códigos de salida

CódigoCuándo
0Todo bien. También hqf harness login, aunque el inicio de sesión del CLI falle
1Un error
2Sin argumentos, un comando desconocido o un flag desconocido en setup, login, repo link o agent remember
78hqf daemon start o hqf daemon run sin credenciales guardadas (systemd no lo reintenta)

Lo que la ayuda no dice

  • hqf config set acepta también worktrees_dir y repos_dir.
  • Existen hqf agent ask, hqf agent subtask y hqf version, aunque la ayuda no los lista.
  • hqf setup tiene --no-daemon y hqf login tiene --app.
  • hqf workspaces también se escribe hqf ws, y hqf harness, hqf harnesses.
  • La guía que lleva el binario (hqf skills get subtask) dice que hqf agent subtask no está disponible. Sí lo está.

En esta página