Commands Reference

npm Scripts

All scripts are defined in package.json and run from the project root.

Command	Description
`npm start`	Start production server (`node server.js`)
`npm run dev`	Start local server with auto-reload (`node --watch server.js`)
`npm test`	Run theme tests
`npm run test:themes`	Run all theme tests (same as `npm test`)
`npm run test:themes:prod`	Test against production environment
`npm run test:themes:screenshots`	Generate theme screenshots for visual comparison
`npm run test:themes:headed`	Run tests with visible browser window
`npm run import-session`	Import a coach session from file (`scripts/import-coach-session.js`)
`npm run scrape-media`	Process curated feed items once
`npm run scrape-media -- --recheck`	Recheck previously failed items
`npm run scrape-media -- --interval=60 --recheck`	Run continuously, checking every 60 seconds

Railway CLI

Railway hosts the production server and PostgreSQL database. Install the CLI with npm i -g @railway/cli and authenticate with railway login.

Command	Description
`railway link`	Connect local project to Railway (run once per clone)
`railway connect postgres`	Open interactive psql shell to production database
`railway shell`	Shell into Railway container
`railway logs`	Stream production logs in real time
`railway variables`	View environment variables

⚠️

Production database: railway connect postgres connects directly to the live production database. Use caution with write operations.

Curated Feed API (Browser Console)

These endpoints can be called from the browser console for debugging the curated content pipeline.

Test Gmail Connection

fetch('/api/curated-feed/test-gmail').then(r => r.json()).then(console.log)

Trigger Email Ingestion

fetch('/api/curated-feed/ingest', { method: 'POST' }).then(r => r.json()).then(console.log)

Check Scraper Status

fetch('/api/curated-feed/scrape-status').then(r => r.json()).then(console.log)

Batch Scrape Pending Items

fetch('/api/curated-feed/scrape-pending?limit=5', { method: 'POST' }).then(r => r.json()).then(console.log)

VS Code Workspace Setup

The project includes a VS Code workspace file that auto-launches development terminals on open.

Workspace File

Open .claude/homeschool-lms.code-workspace in VS Code. This configures the integrated terminal working directory to the project root.

Auto-Launch Terminals

The .vscode/tasks.json defines 4 terminal tasks that start automatically when the workspace opens:

Terminal	Command	Purpose
Railway Postgres	`railway connect postgres`	Interactive psql shell to production DB
Dev Server	`npm run dev`	Local server on port 3000 with auto-reload
PowerShell CLI	`powershell`	General-purpose terminal
Gmail Scraper	`npm run scrape-media -- --interval=60 --recheck`	Continuous curated feed scraper

Enabling Auto-Launch

VS Code may prompt you to allow automatic tasks. To enable:

Open Settings (Ctrl+,)
Search for task.allowAutomaticTasks
Set to "on"

Manual Launch

If auto-launch is disabled, start terminals manually:

Press Ctrl+Shift+P
Type Tasks: Run Task
Select Start All Terminals

PowerShell Tips

Command History Search

Press Ctrl+R in PowerShell to search command history interactively. Start typing to filter previous commands.

Check History Save Location

(Get-PSReadLineOption).HistorySavePath

Common Development Commands

# Start dev server
npm run dev

# Git workflow
git add -A && git commit -m "message" && git push

# Check Railway production logs
railway logs

# Connect to production database
railway connect postgres

Git Workflow

The project uses a single branch: phase-1-student-interface.

Standard Commit

git add -A
git commit -m "Description of changes"
git push origin phase-1-student-interface

Production Deployment

Railway auto-deploys on push to the configured branch. Monitor deployment with railway logs.