CookieCrumbs
Start free

docs · for developers

The CLI

The dashboard for people who ship. Everything the dashboard does to a banner, from your terminal or your CI, with a config file in your repository.

Install and sign in

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

login uses the device flow (approve the code in the dashboard) and stores a token. Options: --token to store an existing cc_* token, --scopes to request specific scopes, --no-open to print the URL instead of opening a browser. whoami shows the token, scopes and workspace in use; logout removes the stored credentials.

Set up a project

npx cookiecrumbs init

init detects your framework (Next.js, React, Astro, Nuxt, SvelteKit or plain HTML), creates or links a site, writes cookiecrumbs.config.ts plus per-language text files, and prints the right install snippet. Options: --site <id> to link an existing site, --name and --domain to create a new one, --env preview|production, --format ts|json, --publish to push right away, -y to overwrite an existing config. link --site <id> connects an existing folder later.

The edit loop

  • pull: fetch the remote draft (three-way: overwrite, keep or conflict).
  • diff: show what push would change, local config against the remote draft.
  • push: validate, save the draft and publish a new version. Options: --env, --note, --material (re-asks consent), --dry-run (lint and diff without writing).
  • status: local against remote state of the linked site. open [page] jumps to the dashboard.
  • versions list · show <n> · rollback <n> · promote <n>: the published history; rollback publishes a copy, promote moves a preview version to production.

Scanning, and scanning in CI

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

scan runs a hosted scan of the linked site. --wait blocks until it finishes and prints the summary (with --timeout, default 30 minutes); --fail-on-unknown exits 1 when unclassified trackers were found and --fail-on-preconsent exits 1 when anything loaded before consent, which is what makes it a CI gate; --sarif <file> writes findings as SARIF 2.1.0 for code-scanning UIs; --states picks the consent states to crawl (no_interaction,reject_all,accept_all); --pages caps the crawl.

The site itself

Everything the dashboard's Settings, Scans, Services, Issues, Domains and Install pages can change, from the terminal. Every command takes --site <id>; without it, the linked site is used.

  • sites list · show · create --name --domain [--languages] · update [--name] [--retention <months>] [--public-versions-feed on|off] [--consent-cookie-name] [--reask-months]
  • schedule shows the scan schedule; schedule set --cadence monthly|weekly|daily --pages <n> --states … --start-urls … --include … --exclude … --robots on|off --pause|--resume. Only the options you pass change, and a value the plan capped is reported rather than hidden.
  • services list · add <name> --category <key> [--provider] [--domain] [--hosts] [--scripts] [--cookies] [--basis] … · update <id> … · remove <id>: the trackers the site declares; they join the declaration and the block list at the next push.
  • issues list [--status] · suppress <id> --reason "…" · unsuppress <id>: the reason is kept with the issue and shown in the audit trail.
  • install status and install check [--url] [--wait]: is cc.js on the page? With --wait the command exits 1 when the install is broken, so it works as a post-deploy check.
  • domains list · verify <id> [--method dns_txt|meta]: prints the exact record or tag to publish.

Records and proof

  • logs export: export consent records (signed JSONL or CSV) through an export job.
  • declaration export: download the public cookie list as html, md or json.
  • export --all: everything about the linked site into a folder.

Workspace

  • tokens list · create · revoke <id>: API tokens; create runs the device flow and prints the secret once.
  • alerts list · ack <id> · resolve <id>: the alert inbox.
  • webhooks list · create · rotate · delete and delivery inspection; usage.
  • templates list · show <id> · save <name> [--from-site] [--config file.json] [--id] · delete <id> · apply <id>: workspace templates from a site's draft or a config file, applied to any number of sites.