Commands

Full reference for all LearnHouse CLI commands.

`setup`

Interactive wizard that generates a complete Docker Compose deployment. See Setup Wizard for details.

npx learnhouse@latest setup

Flag	Description
`--ci`	Non-interactive mode with defaults (for CI/automation)
`--name <name>`	Installation name (default: `default`)
`--domain <domain>`	Domain name (default: `localhost`)
`--port <port>`	HTTP port (default: `80`)
`--admin-email <email>`	Admin email (default: `admin@school.dev`)
`--admin-password <password>`	Admin password (required in `--ci` mode)
`--org-name <name>`	Organization display name (default: `Default Organization`)
`--org-slug <slug>`	Organization slug used in URLs (default: `default`)
`--channel <channel>`	Release channel: `stable` or `dev` (default: `stable`)
`--no-start`	Skip starting services after setup
`--external-db <uri>`	Use an external Postgres instead of the in-container DB
`--external-redis <uri>`	Use an external Redis instead of the in-container Redis
`--docker-ipv6`	Enable IPv6 on the compose network (needed for IPv6-only external DBs)

Use --org-slug to set a custom URL prefix (e.g. --org-slug acme → users browse /orgs/acme). The default is default.

`start`

Start all Docker containers for your deployment.

npx learnhouse start

`stop`

Stop all running containers without removing data volumes.

npx learnhouse stop

`status`

Show the live status of each LearnHouse container.

npx learnhouse status

Displays each service name, container state, health check result, and restart count.

`health`

Run health checks against the running deployment and report the results.

npx learnhouse health

Checks:

Container running state and health
PostgreSQL connectivity (TCP + query)
Redis ping
HTTP health endpoint (/api/v1/health)
Disk usage
Memory and CPU consumption

`logs`

Stream logs from all containers in real-time.

npx learnhouse logs

`config`

Display current installation metadata — version, directory, URL, organization slug, and file locations.

npx learnhouse config

`update`

Update LearnHouse to the latest release or a specific version. See Updates for details.

# Update to latest
npx learnhouse update
 
# Update to a specific version
npx learnhouse update --to 1.4.2
# or using the short form:
npx learnhouse update -v 1.4.2

Flag	Description
`-v, --to <version>`	Pull a specific image tag from `ghcr.io/learnhouse/app` (e.g. `1.4.2`, `v1.4.2`). Defaults to `latest`.
`--migrate`	Run database migrations automatically after restart (no prompt)
`--no-migrate`	Skip database migrations without prompting
`--no-backup`	Skip the pre-upgrade database backup (not recommended for production)

What update does, in order:

Creates a database backup (unless --no-backup)
Stamps an Alembic baseline if your DB was never migrated (installs created before v1.3)
Rewrites the image tag in docker-compose.yml
Migrates uploaded media to a persistent Docker volume (one-time, idempotent)
Pulls the new image (docker compose pull)
Restarts the stack with --pull always
Waits for the health endpoint to respond
Runs alembic upgrade head (unless --no-migrate)

If the migration step fails, the CLI prints the rollback command and exits with a non-zero code. Your pre-upgrade backup is in {installDir}/backups/. To roll back: restore the backup, revert the image tag in docker-compose.yml, and run npx learnhouse start.

`backup`

Create a database backup as a .tar.gz archive containing a pg_dump and optionally your .env file.

npx learnhouse backup

Backups are saved to {installDir}/backups/learnhouse-backup-{timestamp}.tar.gz.

The backup prompt lets you choose between creating a new backup or restoring from an existing one. Pass --restore to skip the prompt.

`restore`

Restore a database from a backup archive. This overwrites the current database.

npx learnhouse restore <archive.tar.gz>

Alternatively:

npx learnhouse backup --restore <archive.tar.gz>

Restore only works with local (Docker) databases, not external Postgres connections. Restart services after restoring: npx learnhouse stop && npx learnhouse start.

The dump uses --clean --if-exists so it can be replayed into an existing database without errors (tables are dropped and recreated). If the .env file was included in the backup, you will be prompted whether to restore it.

`doctor`

Run comprehensive diagnostics to identify issues.

npx learnhouse doctor

Checks:

Docker installation and daemon status
Docker Compose v2 availability
Container health and restart counts
Port availability
DNS resolution (for non-localhost domains)
Disk space (warns below 1 GB)
Docker volume sizes
Log analysis (scans for recent errors)
.env validation (required variables, secret length)
Image freshness (compares local digest against registry)

`deployments`

View and manage deployments on the current machine.

npx learnhouse deployments

Features:

List all LearnHouse deployments with container status
Scale memory limits for learnhouse-app, db, and redis
View current resource usage via docker stats

`env`

Interactive environment variable editor. Edit variables by category:

Domain & Hosting
Database & Redis
Security
AI
Email (Resend only — edit .env directly to set SMTP credentials)
S3 Storage
OAuth

npx learnhouse env

Secret values are masked in the display. Optionally restart services after changes.

`shell`

Open an interactive shell (/bin/sh) inside a running container.

npx learnhouse shell

Displays a list of running containers to choose from.

`dev`

Start a local development environment. See Dev Mode for details.

npx learnhouse dev

Flag	Description
`--ee`	Enable Enterprise Edition features (keeps the `ee/` folder active)
`--admin-email <email>`	Admin email (default: `admin@school.dev`)
`--admin-password <password>`	Admin password (skips the interactive prompt)

Troubleshooting

Containers restart in a loop

Run npx learnhouse doctor — it scans logs and surfaces the root cause. Common causes:

Missing required env var in .env
Port conflict (another process is using port 80 or 5432)
Postgres volume corruption (restore from backup)

`update` migration fails

If npx learnhouse update reports a migration failure:

# 1. Restore your pre-upgrade backup
npx learnhouse restore backups/db-pre-upgrade-*.sql.gz
 
# 2. Revert the image tag in docker-compose.yml to the previous version
# (open the file and change image: ghcr.io/learnhouse/app:<new> back to <old>)
 
# 3. Restart on the old image
npx learnhouse start

Then check the LearnHouse releases page and the GitHub issues for your version before retrying.

Database unreachable after update

The learnhouse-db container may need a moment after startup. Wait 20-30 seconds and run npx learnhouse health. If health checks keep failing, run npx learnhouse logs to see the Postgres logs.

`restore` errors: “relation already exists”

The restore command uses pg_dump --clean --if-exists, which drops existing tables before recreating them. If you see this error, your backup was created with an older CLI version (before v1.4.8). As a workaround:

# Drop and recreate the database, then restore
docker compose exec db psql -U learnhouse -c "DROP DATABASE learnhouse; CREATE DATABASE learnhouse;"
npx learnhouse restore <backup.tar.gz>

PreviousCLI NextDev Mode

Commands

setup

start

stop

status

health

logs

config

update

backup

restore

doctor

deployments

env

shell

dev