gug007/lpm/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, skills, 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 connections [--activity] [--json] — what this machine hosts and what it is connected to, with what each connected computer lets this one's agents copy or run there. --activity lists the latest copies and commands agents made between computers.
• lpm cp [--force] [--json] <SRC> <DST> — copy a file or folder between this computer and one it connects to; one side is NAME:PATH, NAME being any part of a computer's name only it has (as lpm connections lists it), PATH may start with ~. The other computer decides what this one's agents may copy there (nothing until the user turns it on in Settings → Connections), and the user allows each copy in lpm, so the command waits until they answer; keys, credentials and startup files always ask again. A folder lands inside an existing destination folder under its own name; files already there are replaced only with --force (the replaced ones are backed up). Only from a terminal in lpm; an automation's run can't copy. Don't retry a denied copy.
• lpm exec --on NAME[:PATH] [--json] -- COMMAND… — run a command on a computer this one connects to and get what it prints as it prints it, exiting with its exit code. NAME is matched as for lpm cp; NAME:PATH starts in that folder there (its home folder otherwise; write ~ after the colon, so it reads as that computer's home). One quoted argument is run by the shell there as written (&&, pipes, cd); several words are run as one command, each kept whole. Nothing is passed on stdin, and nothing interactive works; use lpm cp to move files. That computer decides whether this one's agents may run commands there (off until the user turns it on in Settings → Connections), and the user allows each command in lpm, or once for the tab, so the command waits until they answer. Stopping lpm exec stops the command there. Only from a terminal in lpm; an automation's run can't. Don't retry a denied command. A prompt may name a place on another computer as NAME:PATH (lpm's @ menu inserts these, e.g. Mac mini:~/storefront); use it as written with lpm exec --on and lpm cp.
• lpm ports [--computers] [--json] — every TCP port this machine listens on, with the project and service holding it, or the process name and PID when nothing of lpm's does (empty project in --json). --computers adds each connected paired computer's ports. Check it before freeing a port by hand: a port held by an lpm service is freed with lpm service <name> stop, not by killing its process.
• 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: a service with a ready check when that check passes, otherwise when its port listens; --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. It refuses inside an automation run, as do duplicate and worktree with --run or --command: the task would run outside the automation. --prompt "/name args" sends that skill's prompt with the arguments filled in, and fails if it still needs a value. A skill made in lpm wins over an agent's own of the same name; any other /name reaches the agent as typed, and so does every --prompt of duplicate and worktree.
• lpm skills list [-p proj] [--global] [--json] — the prompts saved as /name skills, run by typing /name in an agent's input. They are Agent Skills in .agents/skills, so agents read them outside lpm too. Lists only skills made in lpm: the project's and the global ones with each one's folder, description and the values it asks for. --json also gives each list's others: skills not made in lpm, with the agents that read them and their folder. lpm doesn't change their text; in the app they can be filed in folders or converted to lpm skills. Outside a project, the global list only.
• lpm skills show <name> [-p proj] [--global] [--json] — print a skill's prompt, the project's own before a global one of the same name.
• lpm skills add <name> (--prompt TEXT | --file PATH | --stdin) [--description TEXT] [--folder NAME] [--keep-out-of-git] [-p proj] [--global] [--json] — save one in the project's list, kept in git, or with --global in the list every project shares. --keep-out-of-git keeps a project skill out of the repo: it stays in the project folder, is never committed, and syncs to connected computers that hold the same repository. --folder Parent/Child keeps it in a folder inside another. Names are lowercase letters, numbers and single hyphens, and a name a skill not made in lpm already holds is refused. In a prompt {{name}} asks for a value (the last one takes the rest of the arguments), {{branch}}, {{project}} and {{dir}} fill themselves in ({{dir}} is the skill's own folder, so a prompt can point at files kept beside its SKILL.md; a global skill has no {{dir}} in an SSH project), and $ARGUMENTS takes every argument. Single-quote --prompt or use --stdin, so the shell leaves $ARGUMENTS alone.
• lpm skills edit <name> [--prompt TEXT | --file PATH | --stdin] [--description TEXT] [--folder NAME] [--rename NEW] [--to project|global] [--keep-out-of-git | --in-git] [-p proj] [--global] [--json] — change only what is given. An empty --description or --folder clears it; --to moves the skill to the other list. Pass --global to find it in the global list. --keep-out-of-git on a committed skill stages its removal for the user to commit: the file stays, past commits keep a copy, and computers that aren't connected lose it when they pull, so say so first. --in-git lets Git see it again. lpm skills list --json reports keptOutOfGit and tracked for each skill.
• lpm skills rm <name> [-p proj] [--global] [--json] — delete one. Without --global it looks only in the project's list. Delete only when the user asks.
• A project's duplicates and Git worktrees share its skills. A skill Git doesn't hold in a copy lives in the original project and is linked in, so add, edit and rm from any copy change it for all of them, a new one lands in the original, and removing a copy keeps its skills. Commit a new skill from the original. A skill Git holds in a copy stays at that branch's version until the change is merged or pulled.
• 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 update --check [--json] — installed and available lpm versions, an install waiting to start, and whether services still run on an older lpm (services.current: false). lpm update [--stable] installs the newest release (--stable: back from a Beta build to the latest stable one) once no agent is mid-turn and no background action runs — including you, so inside an lpm terminal it installs after your turn ends; it returns at once with state: "scheduled". Never pass --now from an lpm terminal: installing restarts lpm, which closes every terminal (agents reopen in their conversations, services keep running). lpm update --cancel calls off a waiting install. Services stay on the lpm they started on through an update; lpm update --restart-services stops and starts them all on the current one — only when the user asks, since every dev server restarts. Update only when the user asks.
• 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.
• lpm awake [agents|on|off|TIME|+TIME] [--then TIME] [--json] — keep this machine from sleeping, as the app's Keep awake menu does: agents while any agent on it is working or waiting for an answer, then for a while after the last one finishes (--then 10m; 5 min by default); a time such as 45m, 2h or 1h30m; +1h adds an hour to the time left (a set time, or the countdown after agents); on until off. No argument says what is on now. Use it