CLI

Compass has a CLI to help devs run a few scripts locally.

bun run cli --help

Primary file:

• packages/scripts/src/cli.ts

Commands To Know

Command	Implementation	Notes
bun run cli purge-user --email <address> [--apply] [--out report.json]	packages/scripts/src/commands/purge-user.ts	Deletes one user's API, Sync, and SuperTokens data. Defaults to dry-run.
bun run cli backfill-billing [--apply] [--batch-size 500] [--cutoff ISO]	packages/scripts/src/commands/backfill-billing.ts	Places existing accounts without billing status onto a 7-day trial. Defaults to dry-run.
bun run cli purge-corrupt-sync-events [--apply]	packages/scripts/src/commands/purge-corrupt-sync-events.ts	Deletes invalid Sync event documents. Defaults to dry-run.
bun run cli refresh-connection-states [--apply]	packages/scripts/src/commands/refresh-connection-states.ts	Re-derives Sync connection state. Defaults to dry-run.
bun run cli manage-failed-jobs <list|clear|requeue> …	packages/scripts/src/commands/manage-failed-jobs.ts	Operator tooling for Sync jobs that exhausted the self-heal requeue budget. Defaults to dry-run; pass --apply to persist.

Manage exhausted Sync jobs

Requires SYNC_MONGO_URI or sync.mongoUri in compass.yaml pointed at the isolated Sync Mongo database.

export SYNC_MONGO_URI='…'

# Inventory exhausted jobs (JSON to stdout)
bun run cli manage-failed-jobs list

# Clear a stuck failed job so a new enqueue can take its coalescing key
bun run cli manage-failed-jobs clear \
  --id <SyncJobId> \
  --coalescing-key <key> \
  --apply

# Or force another full retry ladder on the same job id
bun run cli manage-failed-jobs requeue --id <SyncJobId> --apply

Prefer dry-run (omit --apply) before writing. Clear is the usual unblock when the underlying condition is durable (for example Google notACalendarUser); also fix or disconnect the Google account so daily calendar-list rediscovery does not recreate the same ladder. The self-heal sweep also auto-clears exhausted jobs whose connection already has a durable lastReadFailureAt marker, so operator clear is mainly for exhausted rows without that marker.

Sync Database Backup / Restore

These scripts are not registered on bun run cli. They dump/restore only the isolated Sync Mongo database (sync.mongoUri / SYNC_MONGO_URI), never the Compass API database. Requires MongoDB Database Tools on PATH.

bun packages/scripts/src/commands/sync-backup.ts [--out DIR]
bun packages/scripts/src/commands/sync-restore.ts --from DIR [--drop]

Use --drop only against a throwaway Sync database during a restore drill.

Historical Migrations

The server-side migration runner and completed Sync cutover tools were removed. Current releases do not ship pending database migrations. An installation that still needs the sub-calendar v1 cutover must use the documented historical v1.0.310 stepping-stone release. Browser-local migrations remain under packages/web/src/common/storage/migrations.