> ## Documentation Index
> Fetch the complete documentation index at: https://docs.driftless.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI: Projects y Cards

> Opera los boards de projects y el loop de cards desde la CLI: crea projects y cards, recorre el loop, define dependencias y valida.

La familia de comandos `project` opera la superficie de [projects](/es/concepts/projects): un project contiene cards, y un agente recorre el board con `project card next`. Todo comando que corre un agente aquí, un humano también puede correrlo. Agrega `--json` a cualquier comando para salida de máquina.

## Projects

| Comando                                | Descripción                                                                                             |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `project add <title>`                  | Crea un project. Opcional `--goal "..."`, `--playbook <slug>`.                                          |
| `project list [--status <s>]`          | Lista projects. `--status` es uno de `active`, `done`, `archived`.                                      |
| `project get <id>`                     | Detalle del project más su índice de cards.                                                             |
| `project update <id> [flags]`          | Actualiza `--status`, `--title`, `--goal` o `--playbook`.                                               |
| `project cards <id> [flags]`           | Lista las cards de un project en orden de board. Filtros: `--status`, `--owner`, `--limit`, `--cursor`. |
| `project apply <id> --file @plan.json` | Aplica un plan declarativo de cards (con `--dry-run`).                                                  |

* **`--goal`** define el terminado del project; **`--playbook <slug>`** apunta a un topic de Knowledge que el agente lee para aprender a ejecutar el project (se guarda como `playbook_slug`).
* El status del project es uno de `active`, `done`, `archived`.

## Cards

Las cards se gestionan bajo `project card`. El status de una card es uno de `todo`, `in_progress`, `blocked`, `review`, `done`.

| Comando                                         | Descripción                                                                |
| ----------------------------------------------- | -------------------------------------------------------------------------- |
| `project card next <project-id>`                | El tick del loop: la próxima card accionable más su context bundle.        |
| `project card add <pid> --title "..." [flags]`  | Crea una card. Ver flags abajo.                                            |
| `project card get <pid> <cid>`                  | Detalle de la card.                                                        |
| `project card update <pid> <cid> [flags]`       | Actualiza título, descripción, acceptance, validate, deps, status u owner. |
| `project card status <pid> <cid> <status>`      | Mueve una card a un status.                                                |
| `project card move <pid> <cid> <to-project-id>` | Mueve una card a otro project.                                             |
| `project card rm <pid> <cid>`                   | Elimina una card.                                                          |

Los `add` y `update` de card aceptan: `--description "..."` (o `@file`), `--acceptance "..."`, `--validate "cmd"`, `--dep <card-id>` (repetible, setea `depends_on`) y `--owner <member-id>` (se guarda como `owner_clerk_id`).

```bash theme={"theme":"github-light"}
driftless project add "Renovación de refunds" --goal "El path de refund es idempotente" --playbook refund-flow
driftless project card add prj_abc \
  --title "Handler de webhook idempotente" \
  --acceptance "Las entregas duplicadas de webhook son un no-op" \
  --validate "npm test -- webhooks" \
  --dep card_setup --owner mem_123
driftless project card next prj_abc                 # card + context bundle
driftless project card status prj_abc card_xyz done
```

`next` elige en orden de prioridad (`in_progress`, luego `review`, luego `blocked`, luego un `todo` ready); un `todo` está ready solo cuando sus `depends_on` están todos en `done`. La verificación es reportar y exponer: la CLI guarda el resultado de `validate`, nunca corre el comando por ti.

## Crear en lote y apply

`project card add --file @cards.json` crea muchas cards de una vez; `depends_on` puede referenciar una card anterior por título o por id. `project apply --file @plan.json` aplica un plan declarativo de project (el plan puede incluir `playbook`).

```bash theme={"theme":"github-light"}
driftless project card add prj_abc --file @cards.json
driftless project apply prj_abc --file @plan.json --dry-run
```

## Flags, archivos y JSON

* **`@file`** lo aceptan `--description`, `--file` (lote de cards) y `apply --file`.
* **`--json`** funciona en cada comando para salida de máquina.
* Las cards se escanean en busca de secrets al escribir, igual que los topics; pasa `--allow-secrets` solo cuando de verdad quieras guardar uno.

## Permisos

Las escrituras de project y card son acciones de miembro del workspace. Por MCP las mismas operaciones requieren el scope `work:write`; una API key actúa con el rol del miembro que la creó. Asignar un owner usa un member id de `driftless member list`.

## Errores

Un `--status` inválido (fuera del enum de card o de project) se rechaza antes de la llamada. Un `--dep` o un `depends_on` de lote que nombra una card desconocida hace fallar la creación. Un `validate` con salida cero es una convención que corre el agente, no un chequeo del servidor.

## Relacionado

* [Projects](/es/concepts/projects) - el concepto y el loop.
* [Comandos de context](/es/cli/context) - topics, notas y gobernanza desde la CLI.
* [API: Projects y Cards](/es/api/projects) - la superficie REST.
* [Guía: Continuar un project entre agentes](/es/guides/project-across-agents) - el workflow de punta a punta.