Command Reference
Setup & lifecycle
| Command | Description |
|---|---|
lerd install | One-time setup: directories, network, binaries, DNS, nginx, watcher |
lerd start | Start DNS, nginx, PHP-FPM containers, and all installed services; warns about port conflicts, and discloses every image it is about to pull or rebuild with its download size before building or pulling any that are missing |
lerd start --dry-run | Report the images a start would pull or rebuild, with their sizes, and exit without downloading or starting anything |
lerd --no-pull <command> | Global flag: skip image pulls and rebuilds unless the image is missing outright, so a metered connection is never spent refreshing something that already works. LERD_OFFLINE=1 does the same for the dashboard, the watcher and the MCP server. Deferred PHP image rebuilds are picked up by the next lerd php:rebuild |
lerd stop | Stop nginx, PHP-FPM containers, and all running services; leaves the lerd-dns forwarder running as install-level plumbing so .test keeps resolving |
lerd quit | Stop all Lerd processes and containers including the UI, watcher, tray, and the lerd-dns forwarder; on macOS also stops the Podman Machine VM |
lerd update | Check for updates and update after confirmation; a package-managed install (apt, dnf, Homebrew) is deferred to that package manager. On a beta it follows the beta line until the stable release of that cycle overtakes it |
lerd update --beta | Update to the latest pre-release build, from a stable version |
lerd update:beta on|off | Offer beta releases to a stable install; with no argument it reports where the install sits |
lerd update --rollback | Revert to the previously installed version |
lerd whatsnew | Show what changed between the installed version and the latest release on the line it follows |
lerd uninstall | Stop all containers and remove Lerd; a package-installed binary is left for apt/dnf/brew to remove |
lerd uninstall --force | Same, skipping all confirmation prompts |
lerd autostart enable | Start Lerd automatically on every login |
lerd autostart disable | Disable autostart on login |
lerd path:disable | Take lerd's shims (php, composer, node…) off your shell PATH; lerd php etc. keep working, and installs/updates stop re-adding the entry |
lerd path:enable | Put lerd's shims back on your shell PATH (the default) |
lerd tray | Launch the system tray applet (detaches from terminal) |
lerd tray icon [default|high-contrast] | Choose the running-icon style; high-contrast shows an always-visible green icon for mixed themes like KDE Breeze Twilight; no argument prints the current style |
lerd tray on / lerd tray off | Turn the tray applet on or off. off quits the running applet, takes lerd-tray.service out of the autostart set, and stops lerd start and lerd install from launching it again; the preference lives in config.yaml under tray.disabled and the dashboard's System page carries the same switch |
lerd dns:check | Walk the DNS chain (container, dnsmasq config, port 5300, dig at 5300, resolver hookup, interface routing, system lookup) and print the layered status with a remediation hint per failure |
lerd status | Health summary: DNS, nginx, PHP-FPM containers, watcher, services, cert expiry, LAN exposure and dashboard remote access; shows a notice if an update is available |
lerd which | Show resolved PHP version, Node version, document root, and nginx config for the current site |
lerd about | Show version, build info, and project URL |
lerd version | Print the installed version, the same line as lerd --version |
lerd licenses | Print the third-party license notices bundled with lerd, the copyright notices and license terms of every Go module linked into the binary and every npm package used to build the embedded dashboard |
lerd man [page] | Browse the built-in documentation in the terminal; pass a page name to jump directly (e.g. lerd man sites) |
lerd tui | Open a btop-style terminal dashboard with live site / service / worker status, per-site detail pane, inline domain and version editing, shell drop-in, log tailing, filter + sort, and global settings |
lerd check | Deprecated alias for lerd site:doctor, which validates .lerd.yaml as one check inside the site's health report |
lerd doctor | Full environment diagnostic: podman, systemd, DNS, ports, PHP images, config validity; also reports how much podman disk is reclaimable, and finishes by sweeping every linked site through the cheap half of site:doctor, one summary line each with lerd site:doctor <domain> for the detail (the audits and the timing lookup stay on the per-site command). Add --fix to apply the safe automatic repairs (confirming each; --yes to skip prompts, --dry-run to preview) and to offer the disk reclaim it reported; privileged and external-state findings are left for you to run. --json emits the findings, each tagged with a fix tier, for tooling |
lerd site:doctor [domain] | App-level health checks for a single site (.lerd.yaml validity: PHP version, workers, services, container block, commands, database service, env file, services the site declares that this machine has never installed, which --fix and the dashboard's Install the missing services button install, ones that are installed but stopped, which the Start the stopped services button starts, services picked in .lerd.yaml that the site's env file does not point at, a key the env file sets more than once, env drift, application key, a configured database that is missing (a SQLite file that is absent or empty, or a MySQL/Postgres schema that does not exist on the service, which --fix and the dashboard's Create the missing database button create), composer/node dependency install + lock, composer audit/npm audit, PHP version range, an nginx vhost that no longer matches what lerd would write for the site, routes running well above the site's typical response time, plus the framework's own checks). A broken database suppresses the framework migration check so the remedy isn't repeated. Defaults to the site in the current directory; pass a domain to target another. Add --json for machine-readable output, or --fix to apply the findings lerd can resolve on its own and re-check |
lerd cleanup | Reclaim podman disk from orphaned lerd images (old PHP build and base images a rebuild left behind), unused images nothing references any more (an old mysql:8.0 after upgrading, or the stranded FROM base of a custom container, keeping each service's current image and its one-back rollback target), and dangling untagged images. Previews the list and confirms before removing. Never touches a tagged image in use, your databases, or volumes |
lerd cleanup --dry-run | Show what would be reclaimed and the approximate size, remove nothing |
lerd cleanup --safe | Only reclaim images provably built by lerd, leave unused and dangling images alone |
lerd cleanup --yes | Remove without the confirmation prompt |
lerd cleanup auto on | Enable automatic cleanup (the default): the watcher's daily deep sweep plus immediate reaping after a PHP rebuild or service update/remove |
lerd cleanup auto off | Disable automatic cleanup; lerd cleanup still works on demand |
lerd cleanup auto status | Show whether automatic cleanup is enabled |
lerd bug-report [-o file] [--log-lines n] [--show-real-names] | Dump doctor output, config files, unit state, recent logs, network state and env vars to a plain-text file you can attach to a GitHub issue. Site names, domains, parked paths, home paths and the username are anonymized by default; --show-real-names keeps raw values |
lerd logs [-f] [target] | Show logs for the current project's FPM container, nginx, a service name, or a PHP version |
Project creation
| Command | Description |
|---|---|
lerd new | Ask for the project name, framework and version, then scaffold, link and set it up |
lerd new <name-or-path> | Ask which framework to scaffold, then take the project through link and setup |
lerd new <name> --framework=<name> | Scaffold a specific framework, skipping the question |
lerd new <name> --framework=<name> --framework-version=<major> | Scaffold an older major instead of the latest |
lerd new <name> -- <extra args> | Pass extra args to the scaffold command |
Project setup
| Command | Description |
|---|---|
lerd init | Wizard: choose PHP version, HTTPS, and services, save .lerd.yaml, apply |
lerd init --fresh | Re-run the wizard with existing .lerd.yaml values as defaults |
lerd setup | Bootstrap a project: runs the lerd init wizard first, then a checkbox list of steps |
lerd setup --all | Run init (or apply saved .lerd.yaml) and all steps without prompting (useful in CI) |
lerd setup --skip-open | Same as above but don't open the browser at the end |
lerd setup --list-steps | Print the steps this directory would run as JSON, without configuring or running anything |
lerd setup --step "<label>" | Run only the named step; repeatable, and it skips the configure phase |
Setup steps include common tasks (composer install, npm install, lerd env) plus framework-specific commands defined in the framework's setup field (e.g. migrations, storage links). See Framework definitions for how to define custom setup commands.
Site management
| Command | Description |
|---|---|
lerd park [dir] | Register every PHP project inside dir as a site, and keep doing so as new ones appear (defaults to cwd) |
lerd unpark [dir] | Remove a parked directory and unlink all its sites |
lerd link [name] | Register the current directory as a site. On a fresh project with no .lerd.yaml, an interactive terminal routes through the lerd init wizard first (PHP version, HTTPS, services) before linking; prompts to import data when laravel/sail is detected in composer.json. Non-PHP projects (Node.js, Python, Go, etc.) must have Containerfile.lerd and .lerd.yaml with container: {port: N} already written before calling this, see Custom Containers |
lerd link [name] --domain foo.test | Register with a custom domain |
lerd unlink [name] | Stop serving the site; defaults to the site in the current directory, and naming one is the way to unlink a site whose directory has moved or been deleted |
lerd sites | Table view of all registered sites |
lerd sites:restore [backup] | Put the site registry back from one of its automatic backups, showing what it would change and confirming first; --list shows what is kept, --force skips the prompt |
lerd open [name] | Open the site in the default browser |
lerd code [name] | Open the site's directory in your editor: the editor command from ~/.config/lerd/config.yaml if set, otherwise the first known GUI editor found on PATH. Run from inside a git worktree it opens the worktree itself |
lerd share [name] | Expose the site publicly via ngrok, cloudflared, or Expose (auto-detected); --serveo, --localhost-run and --pinggy pick the SSH tunnels that need no signup |
lerd share --domain <hostname> | Expose the site on your own Cloudflare-managed hostname via a named tunnel (implies Cloudflare Tunnel); with --ngrok it pins the tunnel to a domain reserved on your ngrok account instead |
lerd share --ngrok-args "<flags>" | Pass flags straight to ngrok for this run, overriding the stored ones |
lerd share:tool [tool] | Show or set the default tunnel tool for lerd share (auto restores auto-detection) |
lerd share:domain [domain] | Show or set the base domain a Cloudflare share is served under, as <site>.<domain> (none forgets it) |
lerd share:ngrok-args [flags] | Show or set the extra flags every ngrok share passes to ngrok, from the CLI and the dashboard alike (none forgets them) |
lerd share:token [provider] [token] | Show whether auth tokens are stored, or set one (none forgets it). A bare token means ngrok, which can then run as a container without being installed; pinggy <token> gives Pinggy shares a stable subdomain |
lerd secure [name] | Issue a mkcert TLS cert and enable HTTPS, updates APP_URL in .env |
lerd secure --renew [name] | Reissue a secured site's TLS cert on demand, resetting its expiry |
lerd unsecure [name] | Remove TLS and switch back to HTTP, updates APP_URL in .env |
lerd pause [name] | Pause a site: stop workers (and custom container if applicable), replace vhost with landing page |
lerd unpause [name] | Resume a paused site: start container, restore vhost, restart workers |
lerd restart [name] | Restart the container serving one site (custom container, FrankenPHP, PHP-FPM or dev server). Run it inside the site's directory or name the site; it does not restart lerd, for that use lerd stop then lerd start |
lerd rebuild [name] | Rebuild the custom container image from Containerfile and restart |
lerd nginx show [site] | Print the site's custom nginx override; --path prints the file path instead of its content |
lerd nginx edit [site] | Open the override in $EDITOR, then validate it with nginx -t and reload on save |
lerd nginx reset [site] | Delete the override and reload nginx; the backups are kept |
lerd nginx … --location | Target the override included inside the block that serves the site instead of the one at the end of the server block, which is the only place a fastcgi_param or proxy_set_header override takes effect. --branch <name> targets a worktree's override on all three. See Nginx overrides |
lerd group add <main> <label> | Group the current site under <main> (name or domain) at <label>.<main-domain>; add --share-db to share the main's database. See Site Groups |
lerd group label <label> | Change the current secondary's subdomain label |
lerd group db <share|separate> | Switch the current secondary between sharing the main's database and keeping its own |
lerd group remove | Ungroup the current secondary, restoring a standalone domain |
lerd group list | List all site groups and their members |
lerd workspace add <name> | Create an empty workspace, a display-only grouping of sites. See Workspaces |
lerd workspace rename <old> <new> | Rename a workspace, keeping its sites |
lerd workspace rm <name> | Delete a workspace; its sites stay linked and become ungrouped |
lerd workspace assign <site> <workspace|none> | Move a site into a workspace, or out of one with none; assign a group main, not a secondary |
lerd workspace move <name> <position> | Reposition a workspace in the display order (0 is first) |
lerd workspace list | List the workspaces and their sites |
lerd env | Configure .env for the current project with lerd service connection settings; backs up the original as .env.before_lerd on first run (skipped if lerd has already written to the file) |
lerd env:restore | Restore .env from the pre-lerd backup (.env.before_lerd) |
lerd env:override [KEY=VALUE ...] | Create/seed a personal, gitignored .env.lerd_override whose values win over lerd's defaults on lerd env; LERD_EXTERNAL_SERVICES= marks services lerd should not start or provision |
lerd env:check | Compare all .env files against .env.example and flag missing or extra keys |
LAN
LAN sharing (per-site, no DNS setup required on clients)
| Command | Description |
|---|---|
lerd lan:share | Start a LAN reverse proxy for the current site on a stable port; prints the URL and a QR code |
lerd lan:unshare | Stop LAN sharing for the current site and release its port |
The proxy runs inside the lerd daemon (lerd-ui), no external tool needed and no internet access required. Any device on the same network can reach the site at http://<your-LAN-IP>:<port> without configuring DNS. The assigned port is stored in sites.yaml and reused across restarts. The proxy rewrites the Host header so nginx routes correctly, and rewrites absolute URLs in HTML/CSS/JS responses so asset and redirect URLs point to the LAN address instead of the .test domain. See LAN sharing for details.
lerd share (without lan:) is different: it wraps an external tunnel tool (ngrok/cloudflared/Expose/SSH) to expose the site to the public internet.
Full LAN exposure (DNS-based)
| Command | Description |
|---|---|
lerd lan:expose | Expose sites, DNS, and the dashboard listener to the LAN |
lerd lan:unexpose | Restrict all Lerd endpoints to loopback |
lerd lan:status | Show site and managed-service LAN exposure state |
lerd lan:services on | Explicitly include managed databases, caches, and services |
lerd lan:services off | Return managed services to loopback without hiding sites |
lerd lan:services status | Show the persisted managed-service setting |
lerd remote-control full-access on | Let authenticated remote sessions run host actions |
lerd remote-control full-access off | Keep host actions local-only (the default) |
lerd remote-control full-access status | Show the persisted host-action setting |
The dashboard System tab and terminal UI expose the same independent settings. Host actions such as reading a site's .env, browsing the filesystem, dropping databases or opening a terminal stay local-only until lerd remote-control full-access on, which only the lerd host can set.
See Remote / LAN Development for the full walkthrough.
PHP
Supported PHP versions: 8.5, 8.4, 8.3, 8.2, 8.1, the prerelease 8.6, and the frozen legacy tier 8.0 and 7.4. The prerelease tier is opt-in the same way (lerd fetch 8.6, lerd isolate 8.6), builds from the 8.6-rc upstream tag while 8.6 is in beta, and is FPM only until FrankenPHP publishes an image for it. The legacy tier is opt-in only (you have to lerd use 7.4 or lerd isolate 7.4 explicitly), pulls from php:7.4-fpm-alpine / php:8.0-fpm-alpine upstream tags, and intentionally skips ext-mongodb (unavailable on those PHP versions). Use the legacy tier for hosted legacy apps; default new projects to 8.4 LTS or 8.5.
| Command | Description |
|---|---|
lerd use <version> | Set the global PHP version and build the FPM image if needed |
lerd isolate <version> | Pin PHP version for cwd: writes .php-version and updates .lerd.yaml if present, then re-links. A version with no image on the machine is built first |
lerd php:list | List all installed PHP-FPM versions |
lerd php:rebuild [version] [--local] | Force-rebuild PHP-FPM images, or install a version this machine does not have (pulls pre-built base by default; --local builds from source) |
lerd fetch [version...] [--local] | Pull pre-built PHP FPM base images from ghcr.io for the given versions, or every released one when none are named; --local builds from source instead |
lerd xdebug on [version] [--mode MODE] [--on-demand] | Enable Xdebug for a PHP version. --mode defaults to debug; accepts coverage, develop, profile, trace, gcstats, or comma combos like debug,coverage. --on-demand sets start_with_request=trigger so nothing auto-connects |
lerd xdebug off [version] | Disable Xdebug |
lerd xdebug status | Show Xdebug enabled/disabled state and active mode for all installed PHP versions |
lerd xdebug pause [site] [--list] [--pid PID] | (experimental, PHP-FPM sites only) Break the IDE debugger into a running worker/CLI process via Xdebug's control socket (xdebugctl). --list shows candidate processes, --pid targets one |
lerd php:ext add <ext> [--apk-deps PKG[,PKG]] | Add a custom PHP extension to every PHP image and rebuild the current version. --apk-deps accepts additional Alpine packages that the extension needs at build time (e.g. --apk-deps libwebp-dev,libpng-dev for gd with WebP support); the package list is persisted in ~/.config/lerd/config.yaml so future rebuilds reapply it |
lerd php:ext remove <ext> | Remove a custom PHP extension from every PHP image and rebuild |
lerd php:ext list | List your declared extensions, and what each PHP version's image actually loaded |
lerd php:pkg add <package...> | Add extra Alpine packages to every FPM image and rebuild the current version; the list is persisted so future rebuilds reapply it |
lerd php:pkg remove <package...> | Remove extra Alpine packages from every FPM image and rebuild |
lerd php:pkg list | List your declared Alpine packages, and what each PHP version's image actually installed |
lerd php:ports add <host:container...> [--php VERSION] | Publish extra host ports on the version's shell (FPM) container so a process in lerd shell is reachable at localhost:PORT; a bare number publishes straight through, and a busy host port shifts to the next free one |
lerd php:ports remove <host...> [--php VERSION] | Unpublish host ports from the version's shell container |
lerd php:ports list [--php VERSION] | List the extra host ports published for a PHP version |
lerd php:ini [version|shared] | Open a PHP version's php.ini in $EDITOR, or the shared file (php:ini shared) applied to every version |
lerd pest:browser install [version] | Set up in-container Pest browser testing: bake musl chromium and Xvfb into the FPM image, download the Playwright registry into a persistent volume, and shim Playwright's glibc browser to it |
lerd pest:browser remove [version] | Remove chromium and Xvfb from the FPM image and disable Pest browser testing (the Playwright cache volume is left intact) |
lerd pest:browser doctor [version] | Diagnose the Pest browser testing setup (plugin, chromium, Xvfb, playwright, shim) for a PHP version |
lerd php:bun install [version] [--pin VERSION] | Install (or update) a musl bun into the container's persistent /root/.bun volume, shared across every PHP version; --pin fixes a specific bun version instead of latest |
lerd php:bun update [version] | Update the container's bun in place (bun upgrade) |
lerd php:bun version [version] | Show the bun version installed in the PHP-FPM container |
lerd php:bun remove | Remove the in-container bun and clear its persistent volume |
lerd dump on | Enable the debug bridge so dump() / dd() calls ship to the lerd dashboard, TUI, and MCP tools |
lerd dump off | Disable the debug bridge and restore FPM containers to their default state |
lerd dump status | Show whether the bridge is enabled and how many events are buffered |
lerd dump tail [--site X] [--branch Y] [--ctx fpm|cli] | Stream captured dumps to the terminal until Ctrl-C |
lerd dump clear | Clear the in-memory dump ring without disabling the bridge |
lerd profile on | Turn the SPX profiler on so every PHP-FPM site's requests are profiled into flame graphs |
lerd profile off | Turn the SPX profiler off |
lerd profile status | Show whether the profiler is on and the SPX web UI URL |
lerd profile open | Open the SPX profiler web UI in the browser |
lerd profile run <command> [args...] | Profile a one-off CLI command (e.g. lerd profile run artisan queue:work) |
lerd profile clear | Delete all captured SPX profile reports |
lerd notify on | Enable lerd notifications globally (dashboard banners + Web Push fanout) |
lerd notify off | Globally mute lerd notifications; bypasses per-device prefs |
lerd notify target <browser|native> | Choose the delivery sink: browser (WebSocket + Web Push) or native desktop notifications (Linux) |
lerd notify status | Show whether notifications are globally enabled and the current delivery sink |
Runtime
Switch the PHP runtime for the current site between shared PHP-FPM and per-site FrankenPHP. See the FrankenPHP runtime page for adapters, worker mode, and limitations.
| Command | Description |
|---|---|
lerd runtime | Print the current runtime for the site in cwd |
lerd runtime frankenphp | Switch to per-site FrankenPHP (non-worker); writes runtime: frankenphp to .lerd.yaml |
lerd runtime frankenphp --worker | Enable FrankenPHP with worker mode (Laravel Octane or Symfony's FrankenPHP adapter with --watch) |
lerd runtime frankenphp --no-worker | Switch to FrankenPHP and explicitly disable worker mode |
lerd runtime fpm | Back to shared PHP-FPM; clears the runtime field from .lerd.yaml |
lerd octane:reload [on|off] | Toggle Octane auto-reload on file changes (octane:start --watch) for the current FrankenPHP worker-mode site; with no argument prints the current state. Needs the chokidar npm package |
Node
| Command | Description |
|---|---|
lerd node:install <version> | Install a Node.js version globally via fnm |
lerd node:uninstall <version> | Uninstall a Node.js version via fnm |
lerd node:use <version> | Set the default Node.js version |
lerd isolate:node <version> | Pin Node version for cwd: writes .node-version, runs fnm install |
lerd node [args...] | Run node using the project's pinned version via fnm |
lerd npm [args...] | Run npm using the project's pinned Node version via fnm |
lerd npx [args...] | Run npx using the project's pinned Node version via fnm |
lerd js:runtime [bun|node|auto] | Pin the current site's JS runtime in .lerd.yaml (the CLI equivalent of the dashboard's bun/Node toggle); with no argument prints the current runtime |
Services
| Command | Description |
|---|---|
lerd service start <name> | Start a service (auto-installs on first use) |
lerd service stop <name> | Stop a service container |
lerd service restart <name> | Restart a service container; refreshes the quadlet first so config edits take effect |
lerd service status <name> | Show systemd unit status |
lerd service list | All services with status, version, and an Update column showing pending updates |
lerd service update <name> [tag] | Pull a newer image and restart; with no tag applies the safe in-strategy update, with a tag targets an explicit upgrade |
lerd service migrate <name> <target-tag> | SQL dump + restore for cross-version mysql / postgres moves; old data dir and dump preserved under ~/.local/share/lerd/backups |
lerd service rollback <name> | Swap back to the previously-running image; toggles, so a second rollback redoes the update |
lerd service expose <name> <host:container> | Publish an extra port on any bundled preset service (persisted, auto-restarts if running) |
lerd service expose <name> <host:container> --remove | Remove a previously exposed port |
lerd service port <name> <port> | Move a service's primary published host port without touching its container-internal port; persisted and auto-restarts if running |
lerd service port <name> <port> --container <cport> | Move a specific mapping of a multi-port service (e.g. Mailpit's 8025 web UI behind the 1025 SMTP primary), named by its container-internal port |
lerd service port <name> --reset | Reset a service to its preset default published port (same as port <name> 0); combine with --container to reset one mapping |
lerd service pin <name> | Pin a service so it is never auto-stopped when no sites use it |
lerd service unpin <name> | Unpin a service so it can be auto-stopped when unused |
lerd service add [file.yaml] | Register a new custom service (from a YAML file or flags) |
lerd service preset [name] | List presets, or install one (use --version for multi-version presets); a store-only preset is fetched on demand |
lerd service search [query] | Browse the external service-preset store; filter by name, description, or family |
lerd service remove <name> [--purge] [--no-snapshot] | Stop and remove a service (custom or default). With --purge, snapshot every database on it, then rename the data dir aside (recoverable as <name>.pre-remove-<ts>). --no-snapshot skips the snapshot |
lerd service domain <service> [domain] [--port N] [--cors|--no-cors] [--remove] | Serve a service on its own HTTPS domain, resolvable from the app container and the browser alike. --port picks the container port for a service exposing several. --cors answers browser preflights, for a page that uploads to the service directly. With no domain, show the current one |
lerd service reinstall <name> [--reset-data] [--no-snapshot] | Stop, remove, and reinstall at the current version, then recreate any linked site's missing database or bucket on it. With --reset-data, snapshot every database on it and rename the data dir aside first. --no-snapshot skips the snapshot |
lerd minio:migrate | Migrate existing MinIO data to RustFS |
Database
| Command | Description |
|---|---|
lerd db:create [name] | Create a database and a <name>_testing database |
lerd db:import [-d name] <file.sql> | Import a SQL dump (defaults to site DB from .env) |
lerd db:export [-d name] [-o file.sql] | Export a database to a SQL dump (defaults to site DB from .env) |
lerd db:shell | Open an interactive MySQL or PostgreSQL shell |
lerd db:snapshot [name] [-A] | Create a named, restorable snapshot of a database |
lerd db:snapshots [--all] | List stored database snapshots |
lerd db:restore <name> [-A] [-f] | Restore a database from a stored snapshot. Snapshots are stored with a timestamp appended, so the name you gave db:snapshot resolves to the most recent snapshot carrying it |
lerd db:snapshot:rm <name> [-A] | Delete a stored database snapshot |
lerd db:snapshot:keep <name> [--off] | Keep an automatic snapshot for good, exempt from retention |
lerd db:snapshot:auto status|on|off|site | Configure scheduled database snapshots, globally or per site |
lerd db:move [--from svc] [--to svc] [--all|--site name] | Move sites' databases between two installed services in the same family and repoint their .env; wizard when run without flags |
Import
| Command | Description |
|---|---|
lerd import sail | Import database and S3/MinIO files from a Laravel Sail project into lerd |
lerd sail import | Alias, natural order when already in a Sail project (lerd sail <anything-else> proxies to vendor/bin/sail) |
lerd import sail --skip-s3 | Import database only, skip S3/MinIO file mirroring |
lerd import sail --no-stop | Leave Sail running after import completes |
lerd import sail --sail-db-name <name> | Override the Sail-side database name (auto-detected by default) |
See Importing from Laravel Sail for full documentation.
Framework workers
| Command | Description |
|---|---|
lerd worker start <name> | Start any named framework worker for the current project |
lerd worker stop <name> | Stop a named framework worker |
lerd worker list | List all workers defined for the current project's framework |
Each worker also gets commands under its own name, generated from the current project's framework definition, in both the name:verb and name verb spellings:
| Command | Description |
|---|---|
lerd queue:start | Start a queue worker for the current project |
lerd queue:stop | Stop the queue worker for the current project |
lerd horizon:start | Start Laravel Horizon for the current project as a persistent background service |
lerd horizon:stop | Stop Horizon |
lerd horizon:reload [on|off] | Toggle Horizon auto-reload on file changes for the current site; with no argument prints the current state. Needs the chokidar npm package |
lerd reverb:start | Start the Reverb WebSocket server for the current project as a persistent background service |
lerd reverb:stop | Stop the Reverb server |
lerd schedule:start | Start the task scheduler (schedule:work) for the current project as a persistent background service |
lerd schedule:stop | Stop the task scheduler |
Which of these exist depends on what the project's framework declares, so a Symfony project gets lerd messenger:start and a Laravel one without laravel/reverb still gets reverb:start (it refuses with the missing package). A :reload command appears for workers whose definition has a reload variant, and start commands carry a flag per tune_command placeholder, so lerd queue:start --help is the authority on what your project accepts. See framework workers.
Idle-suspend
Activity-driven worker suspension: lerd gracefully stops each site's suspendable workers (queue, scheduler, Horizon, Reverb, Stripe listener, Vite) after a period of no activity and resumes them on the next request, CLI command, MCP call, or source-file save. See the idle-suspend page for the full behaviour.
| Command | Description |
|---|---|
lerd idle on | Enable idle-suspend globally |
lerd idle off | Disable idle-suspend and resume every suspended worker |
lerd idle status | Show each site's idle-suspend policy and last-active time |
lerd idle timeout <duration> | Set the idle timeout (e.g. 30m, 2h) |
lerd idle pin <site> | Pin a site so idle-suspend never sleeps it |
lerd idle unpin <site> | Unpin a site so idle-suspend can sleep it again |
Framework definitions
| Command | Description |
|---|---|
lerd framework list | List all available framework definitions and their workers, and the packages the store declares |
lerd framework add <name> | Install a published framework from the store, or author a custom one (flags or --from-file) |
lerd framework remove <name> | Remove a framework definition (confirms if a site still uses it) |
lerd framework prune | Remove installed definitions no site uses |
Stripe
| Command | Description |
|---|---|
lerd stripe:listen | Start a Stripe webhook listener for the current project as a background service |
lerd stripe:listen stop | Stop the Stripe webhook listener |
lerd stripe:config | Show or set the webhook path and secret env key in .lerd.yaml without starting the listener |
Authentication
| Command | Description |
|---|---|
lerd auth ssh [key...] | Load SSH keys into a shared lerd-ssh-agent sidecar so lerd composer can reach private git repositories, including passphrase-protected keys. Defaults to ~/.ssh/id_*. The agent socket lives on a named volume shared into the FPM containers, so it works on macOS where the host agent can't cross the podman-machine boundary. Unlocked keys stay in the agent's memory and clear when it stops |
lerd auth ssh --list | List the keys currently loaded into the agent |
lerd auth ssh --remove | Remove all keys and stop the agent |
Console & runtime passthrough
| Command | Description |
|---|---|
lerd console [args...] | Run the framework's console command (e.g., php artisan for Laravel, php bin/console for Symfony) inside the project's PHP-FPM container |
lerd artisan [args...] | Alias for lerd console, equivalent to php artisan since the php shim also runs inside the FPM container |
lerd a [args...] | Short alias for lerd console / lerd artisan |
lerd test [args...] | Shortcut for lerd artisan test |
lerd <vendor-bin> [args...] | Run any composer-installed binary from the project's vendor/bin directory (e.g. lerd pest, lerd pint, lerd phpstan). Real lerd commands always win over vendor binaries with the same name. |
lerd cpx <package> [args...] | Run a command from any Composer package without adding it to the project, cpx being to Composer what npx is to npm. Uses the globally required binary (lerd composer global require cpx/cpx) and runs it on the PHP version the project is registered on |
lerd shell [version] | Open an interactive shell inside the project's PHP-FPM container, or inside a given version's shared container from anywhere |
AI integration
| Command | Description |
|---|---|
lerd mcp:enable-global | Register lerd MCP at user scope across every supported assistant (Claude Code, Cursor, Junie, Codex, Gemini, Copilot, Antigravity, Windsurf), available in every session regardless of directory |
lerd mcp:disable-global | Unregister the user-scope lerd MCP server and remove the user-scope skill files (inverse of mcp:enable-global) |
lerd mcp:inject | Inject the lerd MCP config and AI skill files into the current project |
lerd mcp:inject --path <dir> | Inject into a specific project directory |
lerd mcp:eject | Remove the lerd MCP config and AI skill files from the current project (inverse of mcp:inject); use --path <dir> to target another directory |
Dashboard
| Command | Description |
|---|---|
lerd dashboard | Open the Lerd dashboard (http://127.0.0.1:7073) in the default browser |
Shell completion
bash
lerd completion bash # add to ~/.bashrc
lerd completion zsh # add to ~/.zshrc
lerd completion fish # add to ~/.config/fish/completions/lerd.fish