spotlightcam/docs/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')

---

Commands

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

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