Flags
Full reference of every ps-lando flag in v1.0, plus exit codes and the v0.x → v1 removal table.
Every flag accepted by ps-lando v1.0, grouped by command. Removed flags from 0.x are listed at the bottom with their replacements. Exit codes are documented in the Exit codes table — the CLI uses contiguous range 64–82 for v1-spec'd error categories (mirrors Info-Zip's 82 + sysexits.h base 64).
create flags
Basic
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
-y, --yes | bool | false | 0.1 | Non-interactive, accept defaults. CI-friendly. |
--ps-version=<v> | string | (picker) | 0.3 | PrestaShop tag (e.g. 8.2.5, 9.1.0). Skips the interactive picker. Legacy --ps alias still works. |
--ps-zip=<path> | string | (download) | 0.3 | Use a pre-downloaded PS zip. Bypasses network entirely. |
-z, --zips=<dir> | string | cwd | 0.1 | Directory with theme + module zips. |
--hummingbird-build | bool | false | 0.4 | After install, build Hummingbird 2.0 assets via node:20 Docker container. |
Theme & preset selection (v1.0+)
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--theme=<name|path|none> | string | (prompt) | 1.0 | Theme name (matches a theme.yml / theme.xml <name> in cwd zips) or .zip path. --theme=none opts out of theme deployment entirely. Skips the interactive select prompt. |
--preset=<name> | string (repeatable) | (theme-name binding) | 1.0 | Built-in (panda, none) or relative path (./presets/foo.ts). Repeat to layer. By default a preset whose name matches the selected theme name activates (e.g. picking panda activates the bundled panda preset). |
--no-preset | bool | false | 1.0 | Disable all presets — overrides the theme-name binding above. |
--force-overwrite-theme | bool | false | 1.0 | Allow overwriting an existing themes/<name>/ directory. |
--allow-incompat-theme | bool | false | 1.0 | Skip the <ps_versions_compliancy> compatibility check. |
--strict-compat | bool | false | 1.0 | Promote a compat warning to a fatal error (exit 76). |
Module selection
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--exclude=<glob> | string (repeatable) | [] | 1.0 | picomatch glob, case-insensitive. Composes with --only. Empty value exits 64. |
--only=<glob> | string (repeatable) | [] | 0.5 | Install ONLY modules matching the glob(s). Composes with --exclude (intersection). |
--no-install-modules | bool | false | 0.1 | Skip the batch install at the end of create. Modules are still copied. |
--no-copy-skipped | bool | false | 0.5.2 | When paired with --exclude / --only, also exclude filtered modules from the copy step. |
--allow-stock-overwrite | bool | false | 1.0 | Allow overwriting stock PS modules. |
--sequential | bool | false | 0.4.2 | Install modules one at a time (default is parallel concurrency 3). |
Hooks & recipes
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--recipes=<names> | string | "" | 0.4 | Comma-separated bundled recipes to run. Used in -y mode. |
--on-hook-failure=<fail|continue> | enum | continue | 0.4 | Whether a failing hook aborts the rest of the pipeline. |
Config & cache
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--config=<path> | string | (cosmiconfig) | 1.0 | Bypass cosmiconfig discovery; load this file directly. |
--no-cache | bool | false | 1.0 | Skip .pslando-cache.json read/write for this run. |
--log-format=<text|json> | enum | text | 1.0 | Mirror of PSLANDO_LOG_FORMAT env. JSON puts decisions on stderr as one event per line. |
--quiet | bool | false | 0.4 | Suppress info / decision logs on stderr. |
--verbose | bool | false | 0.4 | Annotate every resolved-decision line with its source:. |
--help, --version | bool | — | 0.1 | Standard. |
install-modules flags
install-modules (alias im) reuses the --exclude, --only, --no-copy-skipped, --sequential, --allow-stock-overwrite, --config, --log-format, --quiet, --verbose flags from create plus:
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--dry-run | bool | false | 0.4 | Preview install order without invoking PrestaShop. |
--include=<prefix> | string | — | 0.1 | Only install modules whose name starts with <prefix> (legacy; consider --only=<prefix>*). |
init flags (1.0+)
ps-lando init is the interactive scaffolder. Walks through 7 prompts (clack) and writes pslando.config.json, init-scripts/01-example.sh, and a .gitignore entry. See Reference → Config and Reference → Commands.
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
--yes | bool | false | 1.0 | Skip all prompts, write defaults. |
--force | bool | false | 1.0 | Overwrite existing pslando.config.*. Without --force, refuses with exit 82. |
cache clear flags (1.0+)
ps-lando cache clear wipes the local plan cache (.pslando-cache.json).
| Flag | Type | Default | Since | Description |
|---|---|---|---|---|
-y, --yes | bool | false | 1.0 | Skip the confirm prompt. |
db reset / db dump / db restore / doctor / activate-theme
These flags are unchanged in v1.0:
db reset:-y, --yesdb dump:--with-files(bundle SQL +img/+themes/<active>/into a.tar.gz)db restore:-y, --yesdoctor:--fixactivate-theme:--force-sql
Removed flags (BREAKING — v1.0.0)
The four --skip-* group flags from 0.5.x were removed. Running them now exits 64 (UsageError) with a one-line migration hint to stderr. Replacements:
| Removed | Replacement |
|---|---|
--skip-easybuilder | --exclude=steasybuilder* (or modules.exclude in pslando.config.json) |
--skip-blog | --exclude=stblog* (or via the panda preset's group config) |
--skip-social | --exclude=<glob> patterns or preset config |
--skip-marketing | --exclude=<glob> patterns or preset config |
--skip <list> | --exclude=<glob> (per-name patterns also work) |
See the Migrating from 0.x guide for grep recipes to find old flags in CI scripts.
Mutual exclusions
--no-presetcannot be combined with--preset=<name>(exit 64).--exclude=(empty value) exits 64 — supply at least one non-empty pattern.
Exit codes
ps-lando v1.0 uses these exit codes (contiguous range 64–82 for spec'd categories):
| Code | Name | Trigger |
|---|---|---|
| 0 | OK | Success. |
| 1 | GenericError | Catch-all (unknown error / JS exception). |
| 2 | AmbiguousTheme | 2+ themes detected, non-TTY, no --theme=. |
| 64 | UsageError | Unknown / removed flag, bad flag value, empty --exclude=. |
| 65 | SchemaValidationError | pslando.config.* fails the zod schema. |
| 66 | ConfigNotFound | --config=<path> passed but file missing. |
| 67 | PresetNotFound | --preset=<name> resolves to nothing. |
| 68 | CorruptZip | unzip -l fails on a detected zip. |
| 69 | EncryptedZip | Zip is encrypted (Info-Zip exit 82). |
| 70 | UnknownZipShape | Zip has neither theme.yml/.xml nor <name>/<name>.php at root. |
| 71 | DependencyResolutionError | Module / preset dependency cycle or missing dep. |
| 72 | HookExecutionError | Hook script exited non-zero AND --on-hook-failure=fail. |
| 73 | CacheCorruption | .pslando-cache.json is malformed or unreadable. |
| 74 | NetworkError | PS download / npm registry check failed after retries. |
| 75 | LandoStartFailed | lando start returned non-zero. |
| 76 | ThemeIncompatible | <ps_versions_compliancy> mismatch AND --strict-compat. |
| 77 | ThemeOverwriteRefused | themes/<name>/ exists AND no --force-overwrite-theme. |
| 78 | StockModuleOverwrite | A module zip would clobber a PS stock module AND no --allow-stock-overwrite. |
| 79 | DiskFull | Write failed with ENOSPC. |
| 80 | PermissionDenied | Filesystem permission failure (EACCES / EPERM). |
| 81 | InitCancelled | User pressed Ctrl-C during ps-lando init. (Treated as code 0 in some envs — see spec §1.5.) |
| 82 | InitConfigExists | pslando.config.* already exists AND no --force. |
For complete trigger definitions and suggested user actions, see the spec exit-code table.
Defaults in -y mode
When -y is passed without other flags:
| Field | Default |
|---|---|
| Project name | basename of cwd |
| PS version | newest stable from the manifest (currently 9.1.0) |
| Theme | 1 detected → auto-selected. 2+ detected → exit 2 (AmbiguousThemeError) — pass --theme=<name>. 0 detected → vanilla install (bundled classic / hummingbird). |
| Preset | activates if its name matches the selected theme name (e.g. panda → bundled panda preset). --no-preset opts out. |
| Modules | every module zip detected in cwd is auto-checked (= installed). Filter with --exclude=<glob> / --only=<glob>. |
| PHP | 8.2 (PS 9) or 8.1 (PS 8) |
| Database | MySQL |
| Extras | phpMyAdmin + MailHog |
| Child theme | yes, named <project>_child |
| Admin email | admin@example.com |
| Admin password | sandbox1234 |
| Locale | es / es / Europe/Madrid |