Edit

CLI

The LearnHouse CLI is the primary tool for deploying, managing, and developing LearnHouse. It generates and runs a Docker Compose deployment, provides an interactive setup wizard, and starts a full local development environment.

The LearnHouse CLI setup wizard running in a terminal

Package: learnhouse on npm

Installation

You don't need to install the CLI globally. Run the setup wizard with npx:

npx learnhouse@latest setup

On a fresh server, the one-line installers for macOS, Linux and Windows install Docker and Node.js first. See Quick Install for the full install steps.

Requirements

  • Node.js 22 or newer
  • Docker with the Compose v2 plugin (docker compose)

See Requirements for hardware, ports and supported systems.

What It Does

The CLI handles two main workflows:

Production Deployment

The setup wizard generates a complete Docker Compose deployment in ~/.learnhouse/<name> with:

  • LearnHouse app container (ghcr.io/learnhouse/app, which bundles the Next.js web app, the FastAPI backend and the collaboration server)
  • PostgreSQL 16 with pgvector (unless you use an external database)
  • Redis (unless you use an external Redis)
  • Caddy (automatic SSL) or nginx reverse proxy

Each deployment gets a unique ID, so you can run several installations on the same machine. The wizard can also deploy the Enterprise Edition, which uses a different set of images and a license key.

Local Development

The dev command starts PostgreSQL and Redis in Docker and runs the API, web, and collaboration servers locally with hot reload.

Choosing an Installation

Commands act on one installation, picked in this order:

  1. The directory passed with --dir <path> (or the LEARNHOUSE_DIR environment variable)
  2. The current directory, when it contains an installation
  3. The only installation under ~/.learnhouse
  4. With several installations: the only running one, otherwise the most recent one (the CLI prints which one it picked)
npx learnhouse --dir ~/.learnhouse/production status

Quick Reference

CommandDescription
npx learnhouse setupInteractive setup wizard
npx learnhouse startStart all services
npx learnhouse stopStop all services (containers are kept)
npx learnhouse updateUpdate to the latest or a specific version
npx learnhouse statusShow service status
npx learnhouse healthRun health checks
npx learnhouse logsStream container logs
npx learnhouse configShow installation info
npx learnhouse envEdit environment variables
npx learnhouse backupBack up the database, .env and uploaded content
npx learnhouse restore <archive>Restore a backup
npx learnhouse doctorRun diagnostics
npx learnhouse deploymentsView deployments and set resource limits
npx learnhouse scaleSet memory limits per service
npx learnhouse shellOpen a shell in a container
npx learnhouse devStart the development environment

Running npx learnhouse with no command prints the list of available commands.

See Commands for the full reference including all flags, and CLI Environment Variables for the variables the CLI reads and the .env file it writes.