CLI: Collections, Records y Entities

La familia de comandos collection opera el sustrato operacional: una collection es una tabla configurada, un record es una fila tipada, y una entity es una identidad cross-collection. Agrega --json a cualquier comando para salida de máquina. Las lecturas son active-only, acotadas y brief por defecto. collection list devuelve collections activas en una página acotada y paginada por cursor; --status all opta a archived. La búsqueda por intención es collection search <intent>, active-only salvo --include-archived. collection get es brief salvo que pases --view full. El ciclo de vida es explícito: archive, restore y purge son comandos separados — collection update rechaza un --status que toque el ciclo de vida.

Collections

Comando	Descripción
`collection add <name> --archetype <a>`	Crea una collection. `--archetype` es obligatorio, uno de `pipeline`, `analysis`, `content`.
`collection list [--status active\|all] [--owner me] [--limit n] [--cursor c]`	Lista collections activas en una página acotada; `--status all` opta a archived.
`collection search <intent> [--owner me] [--include-archived] [--updated-after <iso>] [--limit n] [--cursor c]`	Búsqueda por intención sobre config de la collection y criterion. Active-only salvo `--include-archived`.
`collection get <id> [--view brief\|full]`	Detalle de la collection; brief por defecto, `full` es explícito.
`collection context <id>`	Resuelve el criterion Knowledge de la collection (qué leer primero).
`collection update <id> [flags]`	Actualiza `--name`, `--schema`, `--views`, `--distill`, `--criterion`. El ciclo de vida va por archive/restore.
`collection archive <id>`	Retira de forma reversible una collection activa.
`collection restore <id>`	Restaura una collection archived a `active`.
`collection purge <id> --dry-run` \| `--expected-version <n>`	Elimina permanentemente una collection archived (owner/admin; version CAS).
`collection doctor`	Audita records fuera de ciclo, violaciones de schema, records drifteados, entities huérfanas.
`collection retrieve <id> [flags]`	Records relevantes más su criterion en una sola llamada acotada.

Flags de configuración en add y update: --schema (el record_schema), --views, --distill (la config distill_policy) y --criterion a,b (los criterion_rel_slugs). Cada uno de --schema, --views, --distill acepta JSON inline o @file.

driftless collection add "Sales Pipeline" --archetype pipeline \
  --schema @schema.json \
  --views '[{"type":"board","group_by":"stage"}]' \
  --criterion "how-we-sell,icp"

Records

Comando	Descripción
`collection records <cid> [flags]`	Lista records. Filtros: `--status`, `--limit`, `--cursor`. Paginación keyset server-side.
`collection retrieve <cid> [flags]`	Búsqueda por intención a escala: records relevantes más el criterion para leer primero. Mismos filtros que records + `--query`, `--fields`, `--view`, `--entity`, `--drift`/`--no-drift`, `--updated-after`.
`collection record add <cid> [flags]`	Agrega un record. `--fields` (JSON o `@file`), `--status`, `--entity <id>`. Un move a un stage terminal devuelve un `context_outcome`.
`collection record get <cid> <rid>`	Detalle del record.
`collection record update <cid> <rid> [flags]`	Actualiza `--fields`, `--status`, `--entity`, `--drift`/`--no-drift`. Un cambio a terminal devuelve un `context_outcome`.
`collection record rm <cid> <rid> [--dry-run]`	Elimina un record. `--dry-run` previsualiza el Entity link removido y las distilled Notes preservadas.

El --status de un record se valida contra los stages propios de la collection: un record solo puede estar en un stage que su collection declara. --entity <id> enlaza el record a una entity — es una propiedad top-level del record, nunca un campo dentro de --fields. Mover un record a un stage terminal dispara el distill_policy, devolviendo un context_outcome (created · already_exists · skipped · failed) — best-effort, nunca bloquea la escritura.

Entities

Las entities se gestionan bajo collection entity. No hay un comando entity de nivel superior en la CLI; el tool MCP driftless_entity y las rutas REST /entities cubren el mismo objeto.

Comando	Descripción
`collection entity add --kind <k> --name <n> [flags]`	Hace upsert de una entity. `--dedup <key>`, `--attrs` (JSON o `@file`).
`collection entity list [--kind <k>]`	Lista entities, opcionalmente filtradas por kind.
`collection entities`	Alias de `entity list`.

--kind y --name son obligatorios en add. Las entities hacen upsert idempotente sobre (kind, dedup_key), así que re-agregar el mismo par actualiza en vez de duplicar.

driftless collection entity add --kind company --name "Acme" --dedup acme.com
driftless collection record add col_abc --fields '{"company":"Acme","mrr":500}' --status new --entity ent_123

Ciclo de vida: archive y purge

collection archive, collection restore y collection purge son las únicas formas de retirar una collection:

# Archive — retira una collection activa (inmutable; solo restore/purge pueden tocarla)
driftless collection archive col_abc

# Purge — solo owner/admin; previsualiza el impacto, luego confirma con version CAS
driftless collection purge col_abc --dry-run
# impact: { version, records, entity_links_removed, distilled_notes_preserved }
driftless collection purge col_abc --expected-version 4
# purge_outcome: purged | already_absent

purge preserva las distilled Notes que engendró la collection (sobreviven al borrado); se cuentan en impact.distilled_notes_preserved. Un reintento de purge tras borrar la collection devuelve already_absent, nunca erroriza. El safe delete de records sigue la misma forma — collection record rm --dry-run previsualiza el Entity link removido y las distilled Notes preservadas (el delete está gateado por membresía del workspace, no por owner/admin).

Retrieve y criterion

collection retrieve <id> devuelve records relevantes y el criterion Knowledge de la collection juntos, así un agente lee el “cómo lo hacemos” del equipo antes de actuar. Filtros: --query, --status, --view, --entity, --updated-after, --drift/--no-drift, --fields, --limit, --cursor. Para solo el criterion (sin records), usa collection context <id>.

Flags, archivos y JSON

@file lo aceptan --schema, --views, --distill, --fields y --attrs.
--json funciona en cada comando.
--cursor pagina una lista/retrieve acotada; el valor es opaco, viene del nextCursor de la página previa.
El distill_policy seteado con --distill es un campo de configuración; declara cómo un record terminal debería destilarse de vuelta en una Nota, devolviendo un context_outcome observable.

Permisos

Las escrituras de collection, record y entity son acciones de miembro del workspace; purge es solo owner/admin. Por MCP requieren el scope work:write. collection doctor, las lecturas y record rm son de nivel miembro.

Relacionado

Collections - el concepto, los arquetipos y los tipos de campo.
Integraciones y Connections - de dónde vienen los records importados.
MCP: Work - la superficie de paridad MCP (driftless_collection, driftless_collection_record, *_purge, *_delete, driftless_entity).
API: Collections, Records y Entities - la superficie REST.
Guía: Operar una Collection con contexto gobernado - el workflow de punta a punta.

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

CLI: Collections, Records y Entities

Collections

Records

Entities

Ciclo de vida: archive y purge

Retrieve y criterion

Flags, archivos y JSON

Permisos

Relacionado

​Collections

​Records

​Entities

​Ciclo de vida: archive y purge

​Retrieve y criterion

​Flags, archivos y JSON

​Permisos

​Relacionado

Collections

Records

Entities

Ciclo de vida: archive y purge

Retrieve y criterion

Flags, archivos y JSON

Permisos

Relacionado