CLI fxc — Documentación de FXCode

Instalar

fxc se distribuye como un binario único para Windows, macOS y Linux: sin Node y sin clonar el repositorio. El instalador detecta tu sistema, descarga el binario de la última versión (público, sin cuenta), comprueba su SHA-256 y lo deja en tu PATH:

# macOS / Linux → ~/.local/bin/fxc
curl -fsSL https://api.fxcode.dev/downloads/cli/install-sh | sh

# Windows (PowerShell) → %LOCALAPPDATA%\fxc\fxc.exe, añadido al PATH de tu usuario
irm https://api.fxcode.dev/downloads/cli/install-ps1 | iex

Para actualizar, vuelve a ejecutar el mismo comando. fxc --version muestra la versión que tienes.

Sistema	Binario (última versión)
Windows x64 (también ARM, emulado)	`fxc-windows-x64.exe`
macOS Apple Silicon / Intel	`fxc-darwin-arm64` / `fxc-darwin-x64`
Linux x64 / ARM64 (glibc)	`fxc-linux-x64` / `fxc-linux-arm64`

También puedes descargar el archivo desde esa tabla, comprobarlo con SHA256SUMS (o el manifiesto latest.json) y dejarlo en tu PATH como fxc. El instalador acepta FXC_VERSION (una versión concreta) y FXC_INSTALL_DIR (otra carpeta). El binario no funciona en Alpine ni en otras distribuciones con musl: usa la instalación desde el repositorio.

Desde el repositorio (desarrollo)

Para trabajar en la propia CLI, compílala con Node y enlázala:

git clone https://github.com/fazt/fxcode.git
cd fxcode && pnpm install
pnpm build:cli
cd apps/cli && npm link

pnpm --filter @fxcode/cli build:bin compila los binarios con Bun en apps/cli/dist-bin/.

Iniciar sesión

# Abre el navegador para aprobar el acceso (sirve con cuentas de GitHub)
fxc auth login --web --api-url https://api.fxcode.dev

# O con email y contraseña
fxc auth login --api-url http://localhost:4000 -e tu@correo.dev

fxc auth me

La sesión se guarda en ~/.fxcode/config.json y se renueva sola. Las variables FXC_API_URL y FXC_TOKEN tienen prioridad sobre ese archivo, útil en CI.

Lo esencial

fxc projects list
fxc tasks list --project-id <id> --status working --json
fxc tasks create -t "Revisar webhooks de Stripe" -s Working --project-id <id> --tag pagos
fxc tasks update <tareaId> --branch feat/fxc-<tareaId>-login --pr https://github.com/acme/web/pull/42
fxc tasks finish <tareaId>          # revisión si estás en una rama, completada en main

fxc ideas add -t "Exportar informes a PDF"
fxc ideas promote <ideaId> --project-id <id>

fxc projects notes add --project-id <id> --file informe.md
fxc changelogs create -v 1.4.0 --project-id <id> --content-file CHANGELOG.md

Grupo	Para qué
`requests`	Solicitudes de clientes: crear con archivos, listar, comentar, descargar; el equipo las clasifica, responde y convierte
`projects`	Proyectos, enlaces, notas y equipo
`tasks`	Tareas, con estados y prioridades por nombre, entorno y versión, enlaces, comentarios, rama y PR, `finish` para terminarlas según el modo del proyecto, `import` para migrar desde Notion, cambios en lote, archivar, fusionar, relaciones, subtareas y la cola de trabajo (`next`)
`ideas`	Ideas sueltas o de proyecto, y su paso a tarea o proyecto
`arch`	La arquitectura: importar, ver, enlazar y foco
`changelogs`, `proposals`, `quotes`, `payments`, `meetings`	El resto del trabajo con clientes
`mcp`	El servidor MCP

Cada comando tiene --help. Los estados se pasan por nombre (-s "No Iniciada"), ignorando mayúsculas y tildes; un prefijo inequívoco también vale (-s work).

Terminar una tarea: ramas y PR

fxc tasks finish <id> termina una tarea según el modo de ramas del proyecto. Sin --branch, toma la rama actual con git rev-parse --abbrev-ref HEAD si estás dentro de un repo:

En una rama distinta de la principal, la tarea pasa a revisión y se guarda la rama: el trabajo está hecho pero falta mergearlo.
En la rama principal, fuera de un repo o en modo Manual, se completa.

git switch -c feat/fxc-<tareaId>-login     # el id en la rama: el webhook de GitHub la reconoce
fxc tasks update <tareaId> -s Working
# … trabajo …
fxc tasks finish <tareaId>                 # → En revisión
fxc tasks finish <tareaId> --branch main   # → completada

fxc tasks update <id> --branch <rama> --pr <url> guarda la rama y el PR a mano ("" los borra). Nunca dejes una tarea en Working si ya no la estás tocando: la guía completa está en Ramas y PR.

Trabajo en paralelo: worktrees

fxc tasks start <tareaId> --worktree [--base main]  # ../<repo>-fxc-<id> en feat/fxc-<id>-<slug>, tarea → Working, sesión registrada
fxc tasks start <tareaId>                           # Working + sesión, en el directorio actual
fxc tasks heartbeat <tareaId>                       # mantiene viva la sesión y envía los archivos tocados
fxc worktrees status --project-id <proyectoId>      # quién trabaja dónde, posibles choques y worktrees para limpiar
fxc worktrees                                       # worktrees locales: rama, tarea, estado, si se mergeó
fxc worktrees prune [--yes]                         # borra los mergeados o terminados (nunca con cambios sin commitear)

start, finish y heartbeat envían la rama, el worktree, la máquina y el agente (--agent <nombre>, o detectado por CLAUDECODE, CODEX, CURSOR_TRACE_ID…; si no, manual). Cualquier otro comando sobre la tarea refresca su sesión. La guía completa está en Trabajo en paralelo (worktrees).

Prioridad, entorno, enlaces y comentarios

fxc tasks create -t "Error al pagar" --project-id <id> --priority Alta --environment producción --version-tag 1.4.0
fxc tasks list --project-id <id> --priority alta --environment producción --version-tag 1.4.0
fxc tasks update <tareaId> --priority Media --environment ""   # "" borra el entorno

fxc tasks links add <tareaId> https://figma.com/file/abc --label Diseño
fxc tasks links list <tareaId>
fxc tasks links remove <tareaId> <enlaceId>

fxc tasks comment <tareaId> -m "Lo reproduzco en Safari" -f captura.png -f informe.docx
fxc tasks comments <tareaId>

fxc settings priorities list
fxc settings priorities seed      # Alta, Media y Baja si el catálogo está vacío

La versión de la tarea va en --version-tag porque --version es el flag global que imprime la versión de la CLI. Las prioridades se pasan por nombre, como los estados. tasks get muestra también el asignado (con o sin cuenta), quién la pidió, sus enlaces y la fecha en que se completó.

Importar tareas

fxc tasks import <archivo.json> --project-id <id> [--dry-run] migra tareas desde Notion u otra herramienta, con comentarios, adjuntos, personas y fechas originales. Reimportar actualiza, no duplica. El formato del archivo está en Importar tareas.

Filtros, cambios en lote, archivar y fusionar

fxc tasks list --project-id <id> --assignee <userId|personId> --priority alta --tag bug --search login
fxc tasks list --changelog-id <changelogId>     # lo que entra en un changelog
fxc tasks list --parent-id <tareaId>            # sus subtareas (none: solo las de primer nivel)
fxc tasks list --archived                       # solo archivadas (--archived all: todas)

fxc tasks create -t "Formulario de login" --project-id <id> --parent-id <tareaId> --changelog-id <changelogId>
fxc tasks update <tareaId> --changelog-id <changelogId> --parent-id ""     # "" los borra

# Los mismos cambios a varias tareas
fxc tasks update --ids a,b,c --status Working --priority Alta --add-tag sprint-3 --remove-tag backlog
fxc tasks update --ids a,b --assigned-person-id <personId> --environment producción --version-tag 1.4.0
fxc tasks update --ids a,b --archive          # o --unarchive

fxc tasks archive <id> <id> …                 # salen de las listas, del avance del proyecto y del MCP
fxc tasks unarchive <id>
fxc tasks merge <destinoId> <origenId> …      # mueve comentarios, adjuntos, enlaces, notas y solicitudes; archiva las de origen

--assignee acepta el id de un usuario o el de una persona sin cuenta (importada de Notion, por ejemplo). Con --ids, update acepta --status, --priority, --assigned-user-id, --assigned-person-id, --environment, --version-tag, --changelog-id, --add-tag / --remove-tag repetibles, --archive y --unarchive.

Relaciones, subtareas y la cola

fxc tasks link-task <id> --blocks <otraId>         # también --blocked-by, --relates-to, --duplicates, --duplicated-by
fxc tasks relations <id>
fxc tasks unlink-task <id> --blocks <otraId>       # o --relation <relationId>

fxc tasks queue <id>                               # al final de la cola del proyecto
fxc tasks queue <id> --first                       # o --after <otraId>, --last
fxc tasks queue --remove <id>
fxc tasks queue --project-id <proyectoId>          # En curso / Sigue / Después
fxc tasks next --project-id <proyectoId> [--mine]  # la tarea que toca tomar ahora

fxc tasks notes <id> [--full]                      # notas enlazadas a la tarea (--full: con su contenido)
fxc tasks link-note <id> <noteId>
fxc tasks unlink-note <id> <noteId>
fxc projects notes add --project-id <id> --file analisis.md --task <tareaId>   # sube las imágenes locales del Markdown

Una tarea bloqueada nunca es «Sigue» mientras su bloqueadora no esté terminada. Al terminar una tarea, el agente pide la siguiente con fxc tasks next. El modelo completo está en Kanban, cola y relaciones.

Fechas, entregas e informe de estado

fxc tasks create -t "Checkout" --project-id <id> --due 2026-11-30 --release 12
fxc tasks update <taskId> --due none --release none        # none las borra
fxc tasks list --project-id <id> --due overdue             # overdue | week (7 días) | none
fxc tasks list --project-id <id> --release 12              # por id o nombre (el nombre necesita --project-id); none = sin entrega

fxc releases list --project <id>                           # ★ = entrega actual
fxc releases create --project <id> --name 12 [--target 2026-11-30] [--status planned|in_progress|delivered] [--description <texto>]
fxc releases update <id|nombre> [--project <id>] [--name <nombre>] [--target <fecha|none>] [--status <estado>] [--description <texto>]
fxc releases show <id|nombre> [--project <id>]             # avance, por estado/prioridad, tareas pendientes y terminadas
fxc releases delete <id|nombre> [--project <id>]           # sus tareas quedan sin entrega
fxc releases link-version <id|nombre> [--project <id>]     # enlaza las tareas cuya versión se llama como la entrega
fxc releases changelog <id|nombre> [--project <id>] [--version <v>] [--no-ai]

fxc projects report <projectId>                            # resumen; --md [--lang es|en] Markdown; --json tal cual

--release y los comandos de entregas aceptan un id o un nombre (el nombre se busca en el proyecto, sin mayúsculas). releases changelog crea el changelog con las tareas terminadas de la entrega (con IA si está configurada; si no, un borrador con la lista). Todo explicado en Entregas e informes.

Solicitudes

Lo que necesita alguien de un proyecto: algo que falla, algo que quiere distinto o una idea. Quien la crea (normalmente el cliente) solo cuenta lo que necesita, sin elegir tipo; nace «Recibida», sin clasificar, y el equipo recibe el aviso, igual que desde el portal.

fxc projects mine                      # tus proyectos y su ID ("You are": client / team)

fxc requests create --project-id <id> \
  -d "El botón Pagar no responde en el móvil. En iPhone, tras elegir la tarjeta, se queda gris." \
  --page-url https://tienda.ejemplo.com/checkout \
  --file ~/Desktop/captura.png --file informe.pdf

fxc requests list --mine                # las tuyas, de todos tus proyectos
fxc requests get <solicitudId>
fxc requests comment <solicitudId> -m "Pasa también en Android" --file video.mp4
fxc requests download <solicitudId> --dir ./adjuntos

# Solo el equipo: clasificar (BUG, FEATURE o IDEA), responder y convertir
fxc requests list --type none           # las que faltan por clasificar
fxc requests respond <solicitudId> --type BUG --response "Lo vemos esta semana"
fxc requests convert <solicitudId> -s "No Iniciada"   # BUG/FEATURE → tarea, IDEA → idea
fxc requests link <solicitudId> --task <tareaId>      # una tarea existente: no crea otra

# En nombre del cliente (una persona, aunque no tenga cuenta), con su fecha original y sin correos
fxc requests create --project-id <id> -d "Lo pidió por WhatsApp" \
  --requester-person-id <personId> --created-at 2025-03-01T10:00:00Z --silent

fxc requests archive <solicitudId>      # creada por error: sale de las listas (unarchive la recupera)
fxc requests list --archived            # solo archivadas (--archived all: todas)
fxc requests delete <solicitudId>

Clasificación. El equipo clasifica cada solicitud al revisarla: BUG (algo está roto) y FEATURE (algo nuevo o distinto) se convierten en tareas; IDEA queda guardada como idea (kind: IDEA). Clasificar una «Recibida» la pasa a «En revisión». convert decide tarea o idea según la clasificación (o fuerza con --task / --idea, y clasifica a la vez con --type). Los nombres antiguos CORRECTION y CHANGE se aceptan como alias de BUG y FEATURE.

Lo que ve el cliente. La columna Status muestra el estado de cara al cliente: Recibida, En revisión, En curso (aceptada o convertida en tarea sin terminar), Lista para revisar (su tarea está en el estado de revisión del proyecto: el cliente la acepta o pide cambios con requests verify), Hecha, Guardada como idea o Descartada (con el motivo en Response). Al cliente no se le enseñan los detalles internos de la tarea, solo si pasó a ser tarea o idea. Recibe un correo, en su idioma, cuando cambia ese estado o cuando el equipo comenta.

Comando	Opciones
`requests create`	`--project-id`, `-d/--description` (lo que necesitas), `-t/--title` (opcional: sale de la descripción), `--type` (opcional y solo para el equipo: `BUG`, `FEATURE`, `IDEA`; también `CORRECTION`/`CHANGE`), `--page-url`, `--priority` (Baja, Media, Alta), `-f/--file <ruta>` repetible; solo el equipo: `--requester-person-id`, `--created-at`, `--silent` (no envía ningún correo)
`requests respond <id>`	`--type` (clasificación), `--status`, `--response` (solo el equipo)
`requests convert <id>`	`--type`, `--task` / `--idea`, `-s/--status` (estado de la tarea), `-t/--title` (solo el equipo)
`requests link <id>`	`--task <tareaId>`: la vincula a una tarea existente del proyecto; queda Aceptada y se cierra al terminar la tarea (solo el equipo)
`requests archive <id>` / `unarchive <id>` / `delete <id>`	Archivar, recuperar o borrar una solicitud creada por error (solo el equipo; el autor puede seguir borrando la suya mientras está Recibida)
`requests comment <id>`	`-m/--message` y/o `-f/--file <ruta>` repetible
`requests verify <id>`	`--accept [--comment <texto>]` o `--changes <comentario>`: el cliente comprueba una solicitud «Lista para revisar» (ver verificación del cliente)
`requests download <id>`	`--dir <carpeta>` (por defecto `./fxcode-request-<id>`); no pisa archivos existentes
`requests list`	`--project-id`, `--status`, `--type` (`BUG`, `FEATURE`, `IDEA` o `none`), `--mine`, `--archived [all]`

Adjuntos. Se aceptan imágenes (png, jpg, gif, webp, heic), PDF, texto (txt, md, csv, json, log), Office (doc, docx, xls, xlsx, ppt, pptx), zip y vídeo (mp4, mov, webm), hasta 10 MB por archivo y 20 archivos por solicitud. El contenido tiene que corresponder a la extensión (un .png que por dentro es otra cosa se rechaza). La CLI lo comprueba antes de crear nada y el API lo vuelve a comprobar con los bytes subidos. Si un adjunto falla después de crear la solicitud, el error da su ID para reintentar con requests comment <id> --file.

Con todos los flags no pregunta nada; si falta --project-id o la descripción (y no hay --title) y hay terminal, los pide. Con --json, create devuelve la solicitud con sus attachments, comment devuelve { comment, attachments } y download la lista de archivos guardados.

Para clientes

Si eres cliente de un proyecto, la CLI y tu asistente (Claude Code, Claude Desktop…) te sirven para dejar solicitudes con capturas y seguir su estado sin entrar en la web. Solo tienes que contar lo que necesitas: no hace falta elegir tipo ni título, el equipo la clasifica al revisarla. Tu cuenta solo ve las solicitudes de tus proyectos, y te llega un correo cuando cambia el estado de una de las tuyas o el equipo te responde.

Si el equipo te invitó, el correo de invitación trae un enlace para entrar sin contraseña (vale 7 días y un solo uso). En la web verás «Mis solicitudes».

1. Instala la CLI: un solo archivo, sin Node ni cuenta:

# macOS / Linux
curl -fsSL https://api.fxcode.dev/downloads/cli/install-sh | sh

# Windows (PowerShell)
irm https://api.fxcode.dev/downloads/cli/install-ps1 | iex

Abre una terminal nueva y compruébalo con fxc --version. Más opciones en Instalar.

2. Inicia sesión con la misma cuenta que usas en la web. Se abre el navegador: entra si hace falta, revisa que el código coincide con el de la terminal y pulsa «Autorizar».

fxc auth login --web --api-url https://api.fxcode.dev
fxc auth me          # "Client only: yes"
fxc projects mine    # el ID de tu proyecto

3. Conecta tu asistente con el servidor MCP y pídele lo que necesites en lenguaje natural, o usa los comandos fxc requests de arriba.

Buenas prácticas para scripts y agentes

Pasa todas las opciones en create y update: sin ellas, la CLI pregunta y un proceso sin terminal se queda esperando.
Usa --json siempre que vayas a leer la salida.
Para textos largos (changelogs, notas), usa --content-file o --file en vez de pasar el texto como argumento; - lee de la entrada estándar.