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 versionhqf 0.1.0Hoy la versión siempre es 0.1.0: ningún build la fija.
Lo común a todos los comandos
| Tema | Comportamiento |
|---|---|
| Configuración | $HQF_HOME/config.json. Sin HQF_HOME, ~/.hqfabric/config.json. El directorio se crea con permisos 0700 y el fichero con 0600 |
| Idioma | Inglés si HQF_LANG seguido de LANG empieza por en; si no, español. LC_ALL no cuenta |
| Flags y argumentos | Los 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 argumentos | Imprime la ayuda y sale con 2 |
| Comando desconocido | comando 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| Flag | Por defecto | Qué hace |
|---|---|---|
--server | el server_url guardado (http://localhost:8080) | URL de la API |
--app | el app_url guardado (http://localhost:3000) | URL de la web, para los enlaces que imprime |
--name | el nombre de la máquina | Nombre de este runtime en la web |
--no-daemon | false | No arranca el daemon al terminar |
Lo que hace, en orden:
- Si no hay sesión guardada, o la que hay no vale, te pide el correo y el código (como
hqf login). - 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. - Detecta los CLIs de agentes de la máquina y los imprime.
- 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.
| Flag | Por defecto | Qué hace |
|---|---|---|
--server | el guardado | URL de la API |
--app | el guardado | URL de la web |
--email | lo pide (propone el guardado) | Tu correo |
--code | lo pide | El 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 2show 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 acmeSin 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 listlink 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| Subcomando | Qué hace |
|---|---|
status (o nada) | Dice si corre, contra qué servidor, el runtime de cada workspace y los CLIs detectados |
start | Lanza hqf daemon run en segundo plano, con la salida en $HQF_HOME/daemon.log, y guarda el PID en daemon.pid |
stop | Manda SIGTERM al PID de daemon.pid y lo borra. No espera a que termine |
run | El daemon en primer plano. Es lo que lanzan start, el servicio systemd de una VPS y el runtime «Usar esta máquina» |
logs | Los ú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:8080Comprueba 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:8080hqf harness
hqf harness list
hqf harness install claude-code
hqf harness install --upgrade codex
hqf harness login claude-codeInstala 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.
| Subcomando | Qué 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.
| Comando | Qué 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.
| Comando | Quién lo lanza | Para qué |
|---|---|---|
hqf egress-proxy [--listen :3128] [--allow host:port,…] | El servidor, en el contenedor hqf-egress de un runtime Docker | Proxy 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 daemon | Aplica las reglas de la tarea a cada herramienta y al cierre |
hqf mcp serve --task <id> | Claude Code en autonomía supervised | El servidor MCP con la herramienta de permisos |
| (askpass) | git, desde el daemon | Con 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.
| Clave | Por defecto | Validación en el CLI | Desde la web |
|---|---|---|---|
server_url | http://localhost:8080 | ninguna | no |
app_url | http://localhost:3000 | ninguna | no |
runtime_name | el nombre de la máquina | ninguna | sí, de 1 a 64 caracteres |
max_parallel | 3 | un entero ≥ 1 | sí, de 1 a 32 |
task_timeout | 2h | una duración de Go (30m, 2h) | sí, de 1 min a 72 h |
worktrees_dir | $HQF_HOME/worktrees | ninguna | no |
repos_dir | $HQF_HOME/repos | ninguna | no |
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
| Fichero | Qué es |
|---|---|
$HQF_HOME/config.json | La configuración |
$HQF_HOME/daemon.pid | El PID del daemon |
$HQF_HOME/daemon.log | El 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.json | Dónde guarda su sesión cada CLI, aprendido en hqf harness login. Siempre bajo $HOME, aunque fijes HQF_HOME |
Variables de entorno
| Variable | Para qué | Por defecto |
|---|---|---|
HQF_HOME | La carpeta de la configuración y del trabajo del daemon | ~/.hqfabric |
HQF_LANG | El idioma de los mensajes (en para inglés) | se mira con LANG |
HQF_HIBERNATE_AFTER | Tras cuánto tiempo sin actividad se hiberna una terminal interactiva de Claude Code | 30m |
HQF_PORT_RANGE | El rango del que sale HQF_PORT para cada worktree | 41000-41999 |
HQF_WORKTREE_GC_INTERVAL | Cada cuánto pasa el recolector de worktrees | 1h |
SHELL | El shell de las terminales | /bin/bash |
HQF_AGENT_ENV_ALLOW | Nombres exactos de variables del entorno del daemon que pasan también a los agentes y a la verificación, separados por comas. Ver abajo | vací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 startLo 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ódigo | Cuándo |
|---|---|
| 0 | Todo bien. También hqf harness login, aunque el inicio de sesión del CLI falle |
| 1 | Un error |
| 2 | Sin argumentos, un comando desconocido o un flag desconocido en setup, login, repo link o agent remember |
| 78 | hqf daemon start o hqf daemon run sin credenciales guardadas (systemd no lo reintenta) |
Lo que la ayuda no dice
hqf config setacepta tambiénworktrees_diryrepos_dir.- Existen
hqf agent ask,hqf agent subtaskyhqf version, aunque la ayuda no los lista. hqf setuptiene--no-daemonyhqf logintiene--app.hqf workspacestambién se escribehqf ws, yhqf harness,hqf harnesses.- La guía que lleva el binario (
hqf skills get subtask) dice quehqf agent subtaskno está disponible. Sí lo está.