spotlightcam/docs/archive/ADMIN_CLI.md

Admin CLI & REPL — spotlight.cam

Administrative console for maintenance tasks inside the backend container. Provides both one‑shot commands and an interactive REPL with app context.

---

Quick Start

• Development REPL: docker compose exec backend npm run cli
• Production REPL: docker compose exec backend-prod npm run cli
• One-shot examples:
  • docker compose exec backend npm run cli -- users:list --limit 20
  • docker compose exec backend npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025

With Makefile shortcuts:

• make dev-cli / make prod-cli
• make dev-up, make dev-down, make prod-up, make prod-down, rebuild variants also available

---

REPL Features

• Default entry: running npm run cli starts a Node.js REPL with:
  • prisma client and bcrypt in context
  • Aliases: u = prisma.user, e = prisma.event, m = prisma.match, ep = prisma.eventParticipant, r = prisma.rating
  • Top‑level await: await u.findMany({ take: 5 })
  • Autocomplete (TAB) from Node REPL
  • Persistent history in .repl_history (best‑effort)
• Run CLI subcommands from inside REPL:
  • .cli users:list --limit 20
  • run('events:checkin --username john_doe --slug warsaw-dance-2025')
• Error handling: CLI errors (e.g., missing flags) do not exit the REPL; the error is printed and you can correct the command and retry.

---

Commands

Cheatsheet

• repl
• users:list [--limit <n>]
• users:create --email <e> --username <u> --password <p> [--first <f>] [--last <l>]
• users:verify --email <e>
• events:list [--limit <n>]
• events:details --slug <slug>
• events:participants --slug <slug> [--limit <n>] [--csv]
• events:import:wsdc [--dry-run] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--limit <n>]
• matches:list [--limit <n>] [--status pending|accepted|completed]
• events:checkin --username <u> --slug <s>
• logs:app [--lines <n>]
• logs:messages [--limit <n>]

users:list

• Description: List users
• Options:
  • --limit <n>: number of rows (default: 50)
• Examples:
  • CLI: npm run cli -- users:list --limit 20
  • REPL: .cli users:list --limit 20

users:create

• Description: Create a user
• Required:
  • --email <email>
  • --username <username>
  • --password <password> (hashed with bcrypt)
• Optional:
  • --first <firstName>
  • --last <lastName>
• Examples:
  • CLI: npm run cli -- users:create --email admin@example.com --username admin --password 'Secret123!'
  • REPL: run("users:create --email a@b.c --username admin --password 'Secret123!'")

users:verify

• Description: Mark user email as verified and clear verification fields
• Required:
  • --email <email>
• Example: npm run cli -- users:verify --email admin@example.com

events:list

• Description: List events
• Options:
  • --limit <n> (default: 50)
• Example: npm run cli -- events:list --limit 10

events:details

• Description: Show details for a specific event by slug
• Required:
  • --slug <event-slug>
• Options:
  • --participants <n>: number of recent participants to show (default: 10)
• Output: basic fields (id, slug, name, start/end, location, worldsdcId), participantsCount, optional check-in token, relation counts, event chat room id and message count, and up to N recent participants
• Examples:
  • npm run cli -- events:details --slug warsaw-dance-2025
  • npm run cli -- events:details --slug warsaw-dance-2025 --participants 25

matches:list

• Description: List matches
• Options:
  • --limit <n> (default: 50)
  • --status <pending|accepted|completed> filter
• Example: npm run cli -- matches:list --status accepted --limit 20

events:checkin

• Description: Attach user to event by username and event slug (simulate QR check-in)
• Required:
  • --username <username>
  • --slug <event-slug>
• Behavior: Upserts into event_participants (idempotent)
• Example: npm run cli -- events:checkin --username john_doe --slug warsaw-dance-2025

events:participants

• Description: List participants for an event by slug
• Required:
  • --slug <event-slug>
• Options:
  • --limit <n>: number of rows (default: 100)
  • --csv: output as CSV (stdout)
• Output: eventId, slug, userId, username, email, firstName, lastName, country, city, joinedAt
• Examples:
  • npm run cli -- events:participants --slug warsaw-dance-2025 --limit 50
  • npm run cli -- events:participants --slug warsaw-dance-2025 --limit 200 --csv > participants.csv

events:import:wsdc

• Description: Import events from worldsdc.com.
• Sources:
  • --source list: parse Event List page (includes Event Location + Country)
  • --source calendar: parse Events Calendar page (title/start/end/url)
  • --source auto (default): try calendar first, then list if calendar parsing yields no events
• Options:
  • --dry-run: show what would be created without writing to DB
  • --since YYYY-MM-DD: only events on/after date
  • --until YYYY-MM-DD: only events on/before date
  • --limit <n>: limit considered items after filtering
  • --update-missing-location: when an event already exists and its location is empty/"Unknown", update it from the imported source (list recommended)
• Examples:
  • npm run cli -- events:import:wsdc --dry-run --since 2024-01-01 --until 2024-12-31
  • npm run cli -- events:import:wsdc --source list --limit 50
  • npm run cli -- events:import:wsdc --source list --update-missing-location
• Field mapping: name, startDate, endDate, sourceUrl, location (from list) or Unknown (from calendar). No updates to participantsCount.
• Dedup strategy: skip when (name, startDate) already exists.
• Alias: events:import:worldsdc (kept for backwards compatibility).

logs:app

• Description: Tail application log file (if configured)
• Options:
  • --lines <n> number of lines from end (default: 200)
• Env:
  • LOG_FILE — absolute/relative path inside backend container (default: ./app.log in working dir)
• Note: For container logs prefer docker compose logs -f backend

logs:messages

• Description: Recent chat messages from DB
• Options:
  • --limit <n> (default: 50)
• Output: message id, time, user, room (event/private), type, first 100 chars

---

Troubleshooting

• REPL not interactive: ensure TTY: docker compose exec -it backend npm run cli
• DB access errors: verify backend container env and DB service are running
• events:checkin says not found: confirm username and slug exist in DB
• Autocomplete: works with Node REPL; press TAB after prisma. to see model methods

---

Security Notes

• CLI has full DB access; restrict usage to SSH + container exec
• Do not expose CLI via HTTP endpoints
• Consider audit logs for sensitive actions if needed

---

Domain Notes

• In spotlight.cam, participantsCount reflects local check‑ins (EventParticipants), not official WSDC participant metrics.
• The WSDC calendar source does not provide reliable location or participant counts; importer intentionally does not set worldsdcId or participantsCount.