Skip to content

CLI Commands

You can use the Command-Line Interface (CLI) provided by Paideia LMS to run the server, manage database migrations, and perform administrative tasks from a terminal window.

Overview

Section titled “Overview”

Paideia LMS is a dual-mode binary that can function as both a web server and a command-line interface. By default, running paideia without any arguments starts the server. CLI commands are available by running paideia <command>.

Running Paideia

Section titled “Running Paideia”

Start Server (Default Behavior):

Terminal window
# Start the server (default behavior)
paideia


# Or explicitly
paideia server

Get Help:

Terminal window
# Display help information and available commands
paideia help

The following message will display in your terminal:

╔═══════════════════════════════════════════════════════╗
║                                                       ║
║      ██████╗  █████╗ ██╗██████╗ ██████╗██╗ █████╗     ║
║      ██╔══██╗██╔══██╗██║██╔══██╗██╔═══╝██║██╔══██╗    ║
║      ██████╔╝███████║██║██║  ██║██████╗██║███████║    ║
║      ██╔═══╝ ██╔══██║██║██║  ██║██╔═══╝██║██╔══██║    ║
║      ██║     ██║  ██║██║██████╔╝██████╗██║██║  ██║    ║
║      ╚═╝     ╚═╝  ╚═╝╚═╝╚═════╝ ╚═════╝╚═╝╚═╝  ╚═╝    ║
║                                                       ║
║               Learning Management System              ║
║                                                       ║
╚═══════════════════════════════════════════════════════╝


Paideia LMS - 0.5.5
                                   Paideia CLI Commands
┌────────────────────────┬───────────────────────────────────────────────────────────────┐
│ Command                │ Description                                                   │
├────────────────────────┼───────────────────────────────────────────────────────────────┤
│ paideia help           │ Show help                                                     │
│ paideia server         │ Start the Paideia server                                      │
│ paideia migrate status │ Show migration status                                         │
│ paideia migrate up     │ Run pending migrations                                        │
│ paideia migrate fresh  │ Drop all database entities and re-run migrations from scratch │
│ paideia migrate dump   │ Dump database to SQL file                                     │
│ paideia sandbox reset  │ Reset sandbox database (only when SANDBOX_MODE is enabled)   │
└────────────────────────┴───────────────────────────────────────────────────────────────┘

Server Commands

Section titled “Server Commands”

paideia server

Section titled “paideia server”

Starts the Paideia LMS web server. This is the default behavior when running paideia without any arguments.

Terminal window
# Start the server
paideia server


# Or simply (default behavior)
paideia

The server will start and listen on the configured port (default: 3001 for backend, 3000 for frontend). The server runs indefinitely until stopped with Ctrl+C.

paideia help

Section titled “paideia help”

Displays the ASCII logo, introduction, and available commands. This provides an overview of Paideia LMS functionality and all CLI commands.

Terminal window
paideia help

paideia version

Section titled “paideia version”

Displays the Paideia LMS version number.

Terminal window
paideia version

Migration Commands

Section titled “Migration Commands”

Paideia LMS provides a comprehensive set of database migration commands for managing your database schema and performing administrative tasks.

paideia migrate status

Section titled “paideia migrate status”

Shows the current status of all database migrations. This displays which migrations have been run and which are pending.

Terminal window
paideia migrate status

Output Example:

Migration Name                    Status
────────────────────────────────────────
1234567890_initial_schema        ✅ Applied
1234567891_add_users_table       ✅ Applied
1234567892_add_courses_table     ⏳ Pending

paideia migrate up

Section titled “paideia migrate up”

Runs all pending migrations. This applies any migrations that haven’t been executed yet.

Terminal window
paideia migrate up

Use Cases:

  • Apply database schema changes after updating Paideia LMS
  • Run new migrations in production
  • Update database structure after pulling code changes

paideia migrate fresh

Section titled “paideia migrate fresh”

Drops all database entities and re-runs all migrations from scratch. This is a destructive operation that will delete all data and schema, then rebuild everything.

Terminal window
# Fresh migration (will prompt for confirmation)
paideia migrate fresh


# Or with force flag to skip confirmation
paideia migrate fresh --force-accept-warning

Use Cases:

  • Complete database reset during development
  • Start with a clean database
  • Rebuild database from scratch

paideia migrate dump

Section titled “paideia migrate dump”

Dumps the entire database to a SQL file. This creates a backup of your database that can be restored later.

Terminal window
# Dump with auto-generated filename
paideia migrate dump


# Dump with custom filename
paideia migrate dump -o my-backup.sql


# Or using long form
paideia migrate dump --output my-backup.sql

Output Location: All dump files are saved to the paideia_data/ directory in your project root. The directory is created automatically if it doesn’t exist.

Filename Format: If no filename is specified, dumps are named paideia-dump-{timestamp}.sql.

Use Cases:

  • Create database backups before major changes
  • Export database for migration to another server
  • Create backups for disaster recovery
  • Automate backups via cron jobs or scripts

Example Output:

Terminal window
paideia migrate dump


# ✅ Database dump completed: paideia_data/paideia-dump-2025-11-02T10-30-45-123Z.sql

Sandbox Commands

Section titled “Sandbox Commands”

Paideia LMS provides sandbox management commands for development and testing environments.

paideia sandbox reset

Section titled “paideia sandbox reset”

Manually resets the sandbox database when SANDBOX_MODE is enabled. This command deletes all user data (students, courses, etc.) while preserving system tables (job logs, migrations, etc.), achieving zero downtime during the reset process.

Terminal window
# Reset sandbox database (only works when SANDBOX_MODE is enabled)
paideia sandbox reset

Requirements:

  • SANDBOX_MODE environment variable must be set to "1" or "true"
  • If sandbox mode is disabled, the command will exit silently

What It Does:

  • Deletes all user data collections (users, courses, enrollments, submissions, etc.)
  • Preserves system tables (payload-jobs, payload-jobs-log, payload-migrations, etc.)
  • Re-seeds the database with fresh data from seed.json (if available)
  • Achieves zero downtime - the application continues operating during the reset

Use Cases:

  • Manual database reset during development
  • Testing database reset functionality
  • Resetting test data without restarting the server
  • Clearing user data while preserving system state

Example Output:

Terminal window
paideia sandbox reset


╔═══════════════════════════════════════════════════════╗
║                                                       ║
║      ██████╗  █████╗ ██╗██████╗ ██████╗██╗ █████╗     ║
║      ██╔══██╗██╔══██╗██║██╔══██╗██╔═══╝██║██╔══██╗    ║
║      ██████╔╝███████║██║██║  ██║██████╗██║███████║    ║
║      ██╔═══╝ ██╔══██║██║██║  ██║██╔═══╝██║██╔══██║    ║
║      ██║     ██║  ██║██║██████╔╝██████╗██║██║  ██║    ║
║      ╚═╝     ╚═╝  ╚═╝╚═╝╚═════╝ ╚═════╝╚═╝╚═╝  ╚═╝    ║
║                                                       ║
║               Learning Management System              ║
║                                                       ║
╚═══════════════════════════════════════════════════════╝


🔄 Resetting sandbox database...
✅ Sandbox database reset completed successfully!

Zero Downtime

The sandbox reset process achieves zero downtime by preserving system tables during the reset. The application continues operating normally while user data is being cleared and reseeded. This is different from migrate fresh, which drops the entire database and causes downtime.

Command Flags

Section titled “Command Flags”

Global Flags

Section titled “Global Flags”

All commands support the following global flags:

--help or -h

Section titled “--help or -h”

Displays help information for the specified command.

Terminal window
paideia migrate --help

Migration Command Flags

Section titled “Migration Command Flags”

--force-accept-warning

Section titled “--force-accept-warning”

Skips confirmation prompts for destructive operations. Use with caution.

Available for:

  • paideia migrate fresh

Example:

Terminal window
paideia migrate fresh --force-accept-warning

-o or --output (for migrate dump)

Section titled “-o or --output (for migrate dump)”

Specifies a custom output filename for database dumps. The filename is relative to the paideia_data/ directory.

Example:

paideia_data/backup-before-update.sql
paideia migrate dump -o backup-before-update.sql

Best Practices

Section titled “Best Practices”

Database Migrations

Section titled “Database Migrations”

  1. Always Backup First: Create a database dump before running migrations in production

    Terminal window
    paideia migrate dump -o backup-before-migration.sql
    paideia migrate up

  2. Check Status: Verify migration status before and after applying migrations

    Terminal window
    paideia migrate status

  3. Test in Development: Always test migrations in a development environment first

  4. Use Fresh Carefully: Only use migrate fresh in development environments

Database Backups

Section titled “Database Backups”

  1. Regular Backups: Schedule regular database dumps

    Terminal window
    # Example cron job for daily backups
    0 2 * * * cd /path/to/paideia && paideia migrate dump -o daily-$(date +\%Y-\%m-\%d).sql

  2. Before Major Changes: Always dump before:

    • Running migrations
    • Updating Paideia LMS
    • Making significant schema changes

  3. Storage: Move dumps to external storage (S3, etc.) for long-term retention

  4. Testing: Regularly test restore procedures to ensure backups are valid

File Organization

Section titled “File Organization”
  • Dump Location: All database dumps are automatically saved to paideia_data/ directory
  • Directory Creation: The paideia_data/ directory is created automatically if it doesn’t exist
  • Git Ignore: The paideia_data/ directory is automatically ignored by git
  • Docker Ignore: The paideia_data/ directory is excluded from Docker builds

Exit Codes

Section titled “Exit Codes”

Paideia CLI commands return appropriate exit codes:

  • 0: Command completed successfully
  • 1: Command failed with an error

This allows for easy integration with scripts and automation tools:

#!/bin/bash
if paideia migrate up; then
    echo "Migrations applied successfully"
else
    echo "Migration failed"
    exit 1
fi

Compiled Binary Support

Section titled “Compiled Binary Support”

All CLI commands work seamlessly with compiled single binary deployments:

  1. Development: Run commands directly

    Terminal window
    bun server/index.ts migrate status

  2. Production: Compile to single binary and run

    Terminal window
    bun build server/index.ts --compile --outfile paideia
    ./paideia migrate status

The CLI mode works with compiled binaries because:

  • Migrations are bundled into the binary at compile time
  • No filesystem dependencies for migration utilities
  • All commands work identically in compiled and non-compiled modes

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

Migration Commands Not Working:

  • Ensure you’re in the correct project directory
  • Check that your database connection is configured correctly
  • Verify that the DATABASE_URL environment variable is set

Dump Command Fails:

  • Check that you have write permissions in the project directory
  • Ensure sufficient disk space is available
  • Verify database connection is active

Server Won’t Start:

  • Check that the required ports are not already in use
  • Verify environment variables are set correctly
  • Check the logs for specific error messages
Section titled “Related Documentation”
Ask DeepWiki
Contribute Community Sponsor