# CLI

`fp` — sin interfaz, programable, orientada a la captura, con un contrato de códigos de salida en el que puedes confiar.

## Qué es

Una CLI de verdad, no un mando a distancia para una ventana abierta. Funciona en un servidor, en CI y en un contenedor sin pantalla.

El código de salida es una superficie pública de la API, tan estable como la salida JSON. Cambiar lo que significa un código es un cambio incompatible.

```bash
fp login
fp capture "the thing I will otherwise forget"
fp query "meeting notes" --ndjson | jq .title
```

## Comandos

| Comando | Hace |
| --- | --- |
| `fp capture [TEXT…]` | captura a la bandeja de entrada desde argumentos, un archivo o stdin |
| `fp add --last` | captura el comando anterior, su salida, su código de salida y su duración |
| `fp ask "QUESTION"` | una respuesta con citas a nivel de bloque que puedes abrir |
| `fp query TEXT` | búsqueda de texto, una página; `--ndjson` emite en streaming. Los filtros estructurados son solo por MCP (`fastpad_query`) |
| `fp watch` | el flujo de cambios del espacio de trabajo, como tubería |
| `fp turns` | propuestas pendientes de revisión |
| `fp diff TURN_ID` | una propuesta como diferencia bloque a bloque |
| `fp turn-abandon TURN_ID` | descarta una propuesta; aceptar una requiere un permiso (abajo) |
| `fp pull` / `fp push` | la copia Markdown, de ida y de vuelta |
| `fp mcp` | un puente MCP local por stdio y un intermediario de credenciales del llavero |
| `fp agents` | principales de agente, scopes, autonomía y última actividad |
| `fp commands --json` | la tabla de comandos, como datos |

`--json`, `--ndjson`, `--quiet`, `--dry-run`, `--profile` y `--timeout` funcionan en todos los comandos. En cualquiera de los dos modos JSON, la prosa nunca toca stdout.

## Códigos de salida

| Código | Significa |
| --- | --- |
| `0` | el efecto solicitado ocurrió |
| `1` | fallo sin clasificar |
| `2` | error de uso: comando desconocido, bandera incorrecta, falta stdin |
| `3` | sin autenticar, o la credencial fue rechazada |
| `4` | el objetivo no existe, o ya no es visible |
| `5` | conflicto: estado caducado, idempotencia, ambigüedad |
| `6` | límite de tasa; `retry_after_ms` va en el documento de problema |
| `7` | aceptado localmente y encolado para reenvío. No es un fallo |
| `8` | denegado por política, incluido todo intento de aprobar una propuesta |

```bash
fp --exit-codes     # prints the contract
```

## La captura nunca falla

`fp capture` no falla ante un error de red. Escribe en una cola local duradera con una clave de idempotencia y sale con 7, y el siguiente comando que funcione la vacía. La captura es la interacción que decide si sigues usando una app de notas, así que tiene que funcionar en un avión.

```bash
fp capture --status    # pending / delivered / failed
fp capture --flush     # drain now; safe from cron or a shell hook
```

## `fp accept` necesita una concesión

Acepta un turno que abrió tu credencial, y solo si esa credencial lleva `turns:accept` — algo que un `fp login` normal nunca pide. Inicia sesión con `fp login --scope turns:accept` para obtenerlo, y la página de aprobación lo nombra. Sin el scope, `fp accept` termina con código 8 y `approve-not-permitted`; ejecuta `fp diff` para leer la propuesta y entrega a una persona la URL con la que termina.

Cada aceptación desde la terminal se registra como cualquier otra aceptación de agente: atribuida a la credencial, marcada como `agent_accepted` y listada en la página de actividad de agentes para que alguien la revise o la revierta.