# Usar el CLI

El CLI es el programa `editorbrain`. Puede trabajar con archivos locales y comunicarse con la API. La [referencia completa](https://editorbrain.com/docs/cli-commands) reproduce la ayuda del código revisado; utiliza la ayuda de tu instalación para comprobar disponibilidad.

## Convenciones

- `--dir` selecciona la carpeta portable; no cambia de cuenta por sí solo.
- Los comandos devuelven JSON, excepto la ayuda. Información del login puede ir a stderr.
- IDs de marca/proyecto no son títulos visibles. Usa discovery antes de operar.
- Un error termina con código de salida distinto de cero. No interpretes stdout parcial como éxito.
- `--user-confirmed`, `--confirm` y `--share-authorized` registran decisiones reales del usuario; no son opciones para «hacer que pase».

## Mapa por tareas

| Grupo | Uso |
| --- | --- |
| `setup`, `login`, `status`, `doctor` | Conexión y diagnóstico |
| `init`, `onboarding`, `brain`, `questions`, `workflow` | Contexto y preferencias |
| `brands`, `projects`, `batches`, `team` | Organización y colaboración |
| `documents`, `pull`, `push`, `resolve`, `validate`, `export` | Archivos y contexto portable |
| `library`, `search`, `narrative`, `styles` | Referencias y métodos de edición |
| `motion`, `media styles`, `sfx` | Recursos visuales y sonoros |
| `resources`, `assets`, `storage` | Material propio y almacenamiento |
| `studio`, `integrations`, `billing` | Herramientas, acceso y saldo |
| `production`, `media inventory/sample/preview/search` | Preparación y verificación local |
| `memory`, `learning`, `feedback`, `improvements`, `review` | Correcciones, aprendizaje y enlaces |
| `skill`, `update`, `keys` | Instalación y mantenimiento |

## Sincronizar sin sobrescribir

```sh
editorbrain pull --project mi-proyecto --dir ./mis-videos --dry-run
editorbrain pull --project mi-proyecto --dir ./mis-videos
editorbrain push --dir ./mis-videos --dry-run
```

Revisa el plan antes de ejecutar `push` sin `--dry-run`. Los conflictos conservan los cambios; no los resuelvas forzando la última copia. `pull --all` amplía lo que se descarga: úsalo solo si necesitas todos esos documentos. Los medios no se sincronizan por estos comandos.

Desde CLI 0.45.1, un rechazo confirmado de tipo/esquema permite guardar los demás
documentos. Lee `status: "partial"`, `synced: false`, `uploaded`, `skipped`
(ruta, código, hint y estado HTTP), `warnings` y `next`. La salida 2 indica acción
pendiente: los omitidos quedan locales sin sincronizar. Actualiza la API según
el hint y reintenta; las revisiones guardadas no se duplican. Los demás errores
detienen el push y conservan los éxitos confirmados. `--dry-run` comprueba validez
local y conflictos, pero no sondea la compatibilidad de escritura del servidor.

## Resolver no es renderizar

```sh
editorbrain validate --dir ./mis-videos
editorbrain resolve mi-proyecto --dir ./mis-videos
editorbrain export mi-proyecto --adapter neutral --dir ./mis-videos
```

`validate` comprueba documentos; `resolve` calcula preferencias efectivas y hashes; `export` prepara un handoff para un motor. Ninguno afirma que haya un video terminado.

## Automatizar

Guarda la salida JSON, comprueba el código de salida y usa IDs/revisiones devueltos. No hagas parsing de mensajes destinados a personas. Para operaciones remotas usa el mismo contexto hasta que termine la operación y vuelve a comprobarlo antes de una nueva fase costosa.

No metas la API key en archivos de marca, argumentos visibles de procesos ni repositorios. Para sistemas sin navegador, `login --key-stdin` acepta una clave suministrada por tu gestor de secretos. `EDITORBRAIN_URL` y `EDITORBRAIN_API_KEY` permiten configuración por entorno.

Consulta [diagnóstico y errores](https://editorbrain.com/docs/errores) y [versiones](https://editorbrain.com/docs/versiones) antes de automatizar actualizaciones.

## Retomar un proyecto sin depender del chat

Este recorrido requiere CLI **0.45.0 o posterior**; la búsqueda y continuidad
remotas requieren API **0.45.0 o posterior**. Comprueba su [disponibilidad](https://editorbrain.com/docs/versiones), `editorbrain projects --help` y
`editorbrain resume --help` antes de actualizar o automatizarla.

```sh
editorbrain projects find "lanzamiento" --brand mi-marca
editorbrain projects list --brand mi-marca --sort recent --limit 20
editorbrain resume mi-proyecto --dir ./mis-videos
editorbrain checkpoint --project mi-proyecto --status in_progress --dir ./mis-videos --expected-checkpoint HASH_DE_RESUME --next "Revisar subtítulos"
```

La búsqueda compara ID, nombre y tema. El orden reciente usa actividad real
de documentos y progreso registrada por el servidor. Para «ayer», el agente calcula el
intervalo de tu zona horaria y envía `--since`/`--before` como fechas UTC. Si hay
varios candidatos, debe resolver la ambigüedad. Continúa con `--after` y el
`nextCursor` devuelto, conservando filtros; deduplica IDs porque el listado sigue
vivo. Reinicia sin cursor si cambias la consulta o quieres una lectura nueva.

`projects find "tema" --local` consulta sin red únicamente el registro privado
de esta computadora; admite `--brand`, pero no fechas ni paginación remota.
Desde CLI 0.45.1, `--local --dir ./mis-videos` valida la carpeta y limita los
resultados a esa raíz canónica registrada, sin explorar ni registrar proyectos.
No recorre todo el disco. `projects link --project mi-proyecto --path ./trabajo
--role work --dir ./mis-videos` registra una carpeta existente; `where mi-proyecto`
comprueba sus ubicaciones. Las preparaciones compatibles del CLI también
registran ubicaciones técnicas sin sustituir vínculos manuales. El registro
`~/.editorbrain/registry.json` conserva la identidad de carpeta, espacio y marca;
no se sincroniza ni permite acceder a los archivos desde otra computadora.

Resume recupera documentos y verifica archivos; presenta versión guardada,
pendientes, cambios de contexto, revisiones y trabajos disponibles. No inicia
render, sube/descarga videos ni gasta. `--rehash` obliga a volver a leer los bytes;
por defecto puede reutilizar un hash cuando los datos del archivo no cambiaron.

El hash esperado evita pisar el hito que guardó otro agente después de tu lectura.
Si hay conflicto, conserva ambas contribuciones y vuelve a leer antes de guardar.
Usa `none` como hash esperado solo cuando la lectura confirmó que no hay checkpoint.
El estado `completed` del checkpoint no aprueba el video. Las revisiones siguen
siendo la fuente de aprobación. Sincroniza el texto con el `push` habitual;
las rutas absolutas y cachés permanecen privadas en el dispositivo.

Desde CLI 0.45.1, `--primary-artifact work=scene.html` y cada
`--dependency role=archivo` explícitos también registran el archivo y calculan
SHA-256/bytes. Con `--artifact`, su lista reemplaza la base y se añaden esas
referencias; sin él se conservan los artefactos previos. Las referencias omitidas
mantienen sus hashes sin volver a leer archivos. No se admiten rutas absolutas,
symlinks ni carpetas como artefactos. Si la API devuelve
`CHECKPOINT_UNSUPPORTED`, actualiza la API y conserva el checkpoint v2 completo.

Archivar o perder una conversación no borra los documentos guardados del proyecto.
Los proyectos antiguos o con un hito completado siguen siendo consultables mientras
conserves sus documentos y permisos. Esta release no añade comandos para archivar
o desarchivar proyectos; `projects unlink` elimina solo un vínculo local, no archivos.

## Encontrar la herramienta adecuada

`editorbrain help --tasks` muestra un mapa por tarea. Usa, por ejemplo,
`editorbrain help sonido`, `editorbrain help revisión` o
`editorbrain help --tasks subtítulos`. Son opciones; no ejecutes toda la lista.
La ayuda por comando existente sigue disponible.

`editorbrain workflow check --project ID` conserva el JSON completo y añade
`nextActions`: hasta tres sugerencias opcionales para ese proyecto. No registrar
un recurso no demuestra que no se haya usado. Puedes usar tus propias
herramientas y adaptar u omitir técnicas cuando encaje con el video, respetando
las reglas obligatorias explícitas y las aprobaciones vigentes.

`--summary` solicita sólo orientación y conserva bloqueos, políticas y estado de
revisión. Para ejecutar, usa el contexto completo (`--details`, o sin flags);
puedes reutilizarlo mientras coincidan tanto su versión editorial como la de
acceso del miembro. El resumen no sustituye un snapshot para aprobar ni gastar.
Estas adiciones requieren una versión de CLI/API que las anuncie.