# CLI hqf (/docs/referencia/cli)

`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 [#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`.

```bash
make cli
./bin/hqf version
```

```text
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 [#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 [#comandos-para-ti]

### `hqf setup` [#hqf-setup]

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

```bash
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:

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`.

```text
→ 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` [#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` [#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]

```bash
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](#claves-de-configuración). Si el daemon corre, reinícialo para
que la lea: la carga al arrancar.

### `hqf workspaces` [#hqf-workspaces]

```bash
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]

```bash
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]

```bash
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` [#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]

```bash
hqf ping http://127.0.0.1:8080
```

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

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

### `hqf harness` [#hqf-harness]

```bash
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`.

| 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-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 [#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 [#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 [#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` [#configjson]

```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 [#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 [#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 [#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:

```bash
HQF_AGENT_ENV_ALLOW=OPENAI_API_KEY,DOCKER_HOST hqf daemon start
```

<Callout type="warn">
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.
</Callout>

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ó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 [#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á.