lpm-cli

lpm is a command-line companion to the lpm desktop app. Verify it is available with lpm --version; if it is missing, install it from the lpm app's Settings.

Key facts

• The project name is inferred from LPM_PROJECT_NAME or the current directory — omit it inside lpm terminals.
• Default output is compact text (cheapest); add --json only when you need to parse the result.
• Exit codes: 0 ok, 2 usage / not found / app not running, 1 failure / timeout.
• config get, config apply, and control commands need the lpm app running; other inspection commands do not.

Commands

• lpm list — all projects, running state, agent counts.
• lpm project [name] [--full] — one project in full (--full adds env maps, action details, terminal history). A started service whose command ended (crashed or exited) shows as exited with its code (runningSource: "exited", exitCode in --json); its pane stays until it is restarted or stopped.
• In lpm list --json and lpm project --json, when isRemote is true, root is the project's ssh.dir: a path on the SSH host, not on this machine. Don't cd into it or read files there locally.
• lpm config resolve [--cwd PATH] [--json] — match a directory to its deepest project root without using LPM_PROJECT_NAME. An SSH project matches only from its local sync mirror ~/.lpm/sync/<project-file-name>, never by root or ssh.dir.
• lpm config validate <file> [--json] — validate syntax, fields, layer rules, and effective merged configuration.
• lpm config get --layer project|repo|global|template [--project NAME | --template NAME] [--create] [--json] — read a config layer with the revision required for a safe write.
• lpm config apply --layer project|repo|global|template [--project NAME | --template NAME] [--create] --if-revision HASH (--stdin | --file PATH) [--json] — validate a candidate and atomically apply it through the running app. Never edit a live config file directly.
• lpm logs [service] [-n 30] [-p proj] — service scrollback, exactly N lines.
• lpm status [project] — live agent statuses (Running/Waiting/Done/Error).
• lpm start [project] [--profile X] / lpm stop [project] — start / stop a project's services.
• lpm service <name> start|stop|restart [-p proj] — one service. restart stops the run still going first, then runs the command again in the same pane.
• lpm wait [project | -p proj] [--service X | --port N | --agent] [--timeout 60] — block until ready; --agent waits until an agent reports after the wait starts and none is still working (your own tab is ignored).
• lpm duplicate [project] [-n N] [--label TEXT]... [--group X] [--run ACTION | --command CMD] [--prompt TEXT] [--include-uncommitted | --exclude-uncommitted] — create parallel working directories. Always pass a --label describing the copy's purpose so it's identifiable in the app — one repeated --label per copy in creation order, <project-name>-<short-description> style such as lpm-fix-auth. Only omit it when you genuinely can't infer a purpose. Output lists each copy's path.
• lpm worktree [project] [-n N] [--label TEXT]... [--group X] [--run ACTION | --command CMD] [--prompt TEXT] [--reinstall-deps] — create linked Git worktrees instead of standalone copies. The same labeling guidance applies. Output lists each worktree's path.
• lpm remove <copy-name> — remove a duplicate. For a linked worktree, this also removes its Git worktree registration and lpm-created branch. Originals and SSH projects (SSH duplicates too) need --force, and their folder is kept; don't use --force unless the user explicitly asks.
• lpm run [action | --command CMD] [--prompt TEXT] [-p proj] — queue in a new app terminal, fire-and-forget.
• lpm set-status <key> <value> / lpm clear-status <key> — report status to the app UI.
• lpm refresh-label [action] [-p proj] — rerun the $(…) commands in an action's labels and emoji (with its menu items' and options') now and redraw labels built from git; no action refreshes every label in the project. Use it after changing what a dynamic label shows, such as at the end of a release script.
• lpm auto-pull [project] [--set on|off|default] / lpm auto-pull --all — whether the app fast-forwards a project from origin by itself, and why. --set changes the project's own autoPull key through the running app, like start/stop; default removes it, so a duplicate or worktree follows its parent, else the Settings mode (Off / Chosen / All, changed only in the app). Change it only when the user asks.