docs · para desarrolladores

La CLI

El panel para la gente que publica. Todo lo que el panel hace con un banner, desde tu terminal o tu CI, con un archivo de configuración en tu repositorio.

Instalar e iniciar sesión

npm i -D cookiecrumbs     # or run everything with npx
npx cookiecrumbs login    # device flow: approve in the dashboard

login usa el flujo de dispositivo (aprueba el código en el panel) y guarda un token. Opciones: --token para guardar un token cc_* existente, --scopes para pedir alcances concretos, --no-open para imprimir la URL en vez de abrir un navegador. whoami muestra el token, los alcances y el espacio de trabajo en uso; logout elimina las credenciales guardadas.

Configurar un proyecto

npx cookiecrumbs init

init detecta tu framework (Next.js, React, Astro, Nuxt, SvelteKit o HTML plano), crea o vincula un sitio, escribe cookiecrumbs.config.ts más archivos de texto por idioma e imprime el snippet de instalación correcto. Opciones: --site <id> para vincular un sitio existente, --name y --domain para crear uno nuevo, --env preview|production, --format ts|json, --publish para subir de inmediato, -y para sobrescribir una configuración existente. link --site <id> conecta una carpeta existente más tarde.

El ciclo de edición

pull: obtiene el borrador remoto (a tres vías: sobrescribir, conservar o conflicto).
diff: muestra lo que cambiaría push, configuración local frente al borrador remoto.
push: valida, guarda el borrador y publica una nueva versión. Opciones: --env, --note, --material (vuelve a pedir consentimiento), --dry-run (lint y diff sin escribir).
status: estado local frente a remoto del sitio vinculado. open [page] salta al panel.
versions list · show <n> · rollback <n> · promote <n>: el historial publicado; rollback publica una copia, promote pasa una versión de vista previa a producción.

Escanear, y escanear en CI

npx cookiecrumbs scan --wait --fail-on-unknown --fail-on-preconsent --sarif findings.sarif

scan ejecuta un escaneo alojado del sitio vinculado. --wait bloquea hasta que termina e imprime el resumen (con --timeout, 30 minutos por defecto); --fail-on-unknown sale con 1 cuando se encontraron rastreadores sin clasificar y --fail-on-preconsent sale con 1 cuando algo cargó antes del consentimiento, que es lo que lo convierte en una puerta de CI; --sarif <file> escribe los hallazgos como SARIF 2.1.0 para interfaces de análisis de código; --states elige los estados de consentimiento a rastrear (no_interaction,reject_all,accept_all); --pages limita el rastreo.

El propio sitio

Todo lo que las páginas Configuración, Escaneos, Servicios, Problemas, Dominios e Instalar del panel pueden cambiar, desde el terminal. Cada comando acepta --site <id>; sin él, se usa el sitio vinculado.

sites list · show · create --name --domain [--languages] · update [--name] [--retention <months>] [--public-versions-feed on|off] [--consent-cookie-name] [--reask-months]
schedule muestra el calendario de escaneo; schedule set --cadence monthly|weekly|daily --pages <n> --states … --start-urls … --include … --exclude … --robots on|off --pause|--resume. Solo cambian las opciones que pasas, y un valor limitado por el plan se informa en lugar de ocultarse.
services list · add <name> --category <key> [--provider] [--domain] [--hosts] [--scripts] [--cookies] [--basis] … · update <id> … · remove <id>: los rastreadores que declara el sitio; se incorporan a la declaración y a la lista de bloqueo en el siguiente push.
issues list [--status] · suppress <id> --reason "…" · unsuppress <id>: el motivo se guarda con el problema y se muestra en el registro de auditoría.
install status e install check [--url] [--wait]: ¿está cc.js en la página? Con --wait el comando sale con 1 cuando la instalación está rota, así que sirve como comprobación posdespliegue.
domains list · verify <id> [--method dns_txt|meta]: imprime el registro o la etiqueta exactos que hay que publicar.

Registros y prueba

logs export: exporta registros de consentimiento (JSONL o CSV firmado) mediante un trabajo de exportación.
declaration export: descarga la lista pública de cookies como html, md o json.
export --all: todo lo del sitio vinculado en una carpeta.

Espacio de trabajo

tokens list · create · revoke <id>: tokens de API; create ejecuta el flujo de dispositivo e imprime el secreto una vez.
alerts list · ack <id> · resolve <id>: la bandeja de alertas.
webhooks list · create · rotate · delete e inspección de entregas; usage.
templates list · show <id> · save <name> [--from-site] [--config file.json] [--id] · delete <id> · apply <id>: plantillas del espacio de trabajo a partir del borrador de un sitio o de un archivo de configuración, aplicadas a cualquier número de sitios.