lpm run

Run package scripts and configured tasks. Use task dependencies to put checks before builds, and workspace filters to select packages.

lpm run [OPTIONS] <SCRIPTS>... [-- <ARGS>...]

Quickstart

lpm run build
lpm run lint test
lpm run lint test --parallel --stream
lpm run test -- --run

Without lpm.json, LPM CLI uses the scripts in package.json. It adds project and workspace executables from node_modules/.bin to the command's PATH.

You can run the command from a subdirectory. An ordinary run acts on the nearest directory at or above the current one that has a package.json or an lpm.json, stopping before your home directory. LPM CLI prints that directory when it is not the current one. Scripts run in that directory, as npm runs them.

Configure lpm.json

{
  "tasks": {
    "check": {
      "command": "tsc --noEmit"
    },
    "build": {
      "command": "vite build",
      "dependsOn": ["check"],
      "env": "production",
      "cache": true,
      "inputs": ["src/**", "index.html", "vite.config.ts", "package.json"],
      "outputs": ["dist/**"]
    },
    "verify": {
      "dependsOn": ["check", "build"]
    }
  }
}

lpm run build
lpm run build --env staging --no-cache
lpm run verify

The build runs after check succeeds. The verify task groups prerequisites and needs no command of its own.

A task's command overrides the package script with the same name. Without this field, LPM CLI uses the package script. Projects can define commands entirely in lpm.json.

See the configuration reference for the complete schema.

Command arguments and hooks

lpm run build -- --mode staging

Arguments after -- go to each executed main task, including prerequisites. They do not go to package pre/post hooks. Shell metacharacters in forwarded arguments remain argument data. On Windows, forwarded arguments cannot contain line breaks.

Package scripts run pre<name>, the main script, then post<name>. A failed phase stops the later phases. An explicit task command does not use package pre/post hooks.

Each package phase receives npm script context, including its package identity, declared command, and original invocation directory.

Task order and failures

Without --parallel, independent tasks keep the order from the command line. Prerequisites always run before their dependents.

lpm run lint test build --parallel
lpm run lint test build --parallel --no-bail --stream

By default, a failure prevents the next batch from starting. Already running tasks finish. With --no-bail, independent tasks continue. Tasks whose prerequisites failed remain skipped.

--stream shows live output with task prefixes, including sequential runs and levels with one task. Cached logs use the same prefixes. The global color setting also applies to streamed output. Parallel output is otherwise buffered per task. Captured logs have a 10 MiB limit per stream across the task's phases. Live output continues after the capture limit.

A single task without prerequisites preserves its child exit code. A run with several tasks returns the number of failed tasks, capped at 255. Workspace runs return a nonzero status if a scheduled member fails.

Workspaces

lpm run build --all
lpm run build --filter web --filter api
lpm run build --filter './packages/*' --workspace-concurrency 2
lpm run test --affected --base origin/main
lpm run build --filter-prod '...shared'

Workspace modes require a workspace, which LPM CLI discovers from the current directory. Ordinary single-package runs use the nearest project, as described in the quickstart.

Repeated filters select the union of their matches. Filters and --affected also combine by union. --all cannot be combined with either filter flag or --affected.

Filters match package names, paths, dependency closures, or Git changes. For example, --filter core does not match @babel/core. Use --filter '*/core' for scoped names. See workspace filters for the full grammar.

Upstream tasks

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

The selected package's build waits for build in its upstream workspace dependencies. This expansion covers the full dependency chain and can include packages outside the original filter. LPM CLI checks the expanded graph before it starts task processes.

With --no-bail, other selected members continue after a failure. A failed explicit ^task prerequisite still prevents its dependent task from running. A local run without workspace selection rejects reachable ^task dependencies. Use --filter or --all to run those prerequisites.

Concurrency and changed files

--workspace-concurrency <N> limits concurrent members within each dependency level. The default comes from lpm.toml under [workspace].concurrency, then ~/.lpm/config.toml under workspace-concurrency, then available processors. --parallel separately controls independent tasks inside each member.

lpm run test --affected --changed-files-ignore-pattern '**/README.md'
lpm run test --affected --test-pattern '**/*.test.js'

Ignored paths do not affect Git-based selection. Test-only changes still select their package, but do not select its dependents through affected-package expansion. Project defaults also come from the matching keys under lpm.toml's [workspace] table.

Environments and runtimes

lpm run start --env staging
lpm run start --no-env-check

Environment selection uses --env, then tasks.<name>.env, then env.<name>, then the default environment. Named environments can define an inheritance chain or a custom file path. Standard loading reads .env, .env.local, .env.<MODE>, then .env.<MODE>.local. Without a mode, it reads the first two files.

Later files override earlier files. Safe inherited values take precedence over file values. Project secrets from lpm env override file values. Configured files and symlinks must remain inside the project.

LPM CLI strips inherited credentials and protected runtime variables before it starts project commands. Explicit project secrets remain available. Files, secrets, and schema defaults cannot inject protected runtime hooks such as NODE_OPTIONS.

The environment schema checks effective values and supplies configured defaults. --no-env-check skips value checks and schema defaults. Declaration errors in lpm.json always stop the command.

Runtime selection uses the project's runtime configuration, including supported version files. Missing managed runtimes can download automatically. By default, the selected Node version must satisfy applicable engines.node requirements. The command does not install project dependencies. Use lpm install first.

Cache task results

A task needs cache: true and nonempty outputs to use the cache. Only successful results enter the cache.

lpm run build
lpm run build --no-cache

The cache key includes the command, arguments, input files, environment, runtime identity, and prerequisite identities. An empty inputs list uses the default source and configuration patterns. Declare additional inputs if the build reads other files.

By default, inherited variables also affect the key. cacheEnv selects those inherited names. An empty array excludes inherited values. Variables loaded from project files, local secrets, and schema defaults remain cache inputs. Include every inherited value that can change the output.

A cache hit restores outputs and replays captured logs without running the task. The restore stages files inside the project's .lpm/ directory, which Git ignores. Files in a .lpm/ directory are never task outputs, also a workspace member's and under any spelling a file system takes for .lpm, another letter case or a zero-width mark on HFS+ or in a Linux casefold directory. Neither are files in a .git directory, under any spelling Git reads as one, or in a directory Git reads as a Git directory under another name, such as a bare repository at vendor/tool.git, where a restored hook would run, nor the project's LPM records at its root: lpm.lock, lpm.lockb, lpm-sources.json, lpm-agent-skills.json, and lpm-changes/, which LPM writes itself. On a volume that makes short names (NTFS, FAT), that holds for their short names too, such as LPM-SO~1.JSO for lpm-sources.json, from Windows or another system, as WSL's /mnt/c is. A cached artifact that holds such files, or writes into such a directory in the project, counts as a cache miss, so the task runs. These checks go by names, links and what a Git directory holds, not by mounts: a mount you place inside a declared output, such as a bind mount of another directory, receives what a restore writes there, as it would from any other tool. The local cache is under ~/.lpm/cache/tasks/, or $LPM_HOME/cache/tasks/ when LPM_HOME is set. With remoteCache.enabled, LPM CLI also uses the hosted cache. Remote cache failures become cache misses.

Use lpm cache to inspect or clear cached results. See remote task cache for account setup and CI configuration.

Watch finite tasks

lpm run build --watch
lpm run verify --watch --parallel --stream

Watch mode runs one requested task and its prerequisites, then waits for changes. Each run finishes before another starts. Changes during a run schedule a later run. For development servers, use lpm dev or the framework's own watch mode.

Watch mode uses the inputs of the scheduled tasks and ignores their declared outputs. Use a directory glob such as dist/** for a generated tree, including its directory changes. It also ignores .git, node_modules, .lpm, and common editor temporary files. Task configuration changes update the graph and watch scope. Restart the session after runtime-pin changes.

On macOS, periodic metadata checks recover missed change notifications.

Watch runs bypass the task cache. --watch cannot be combined with multiple requested task names, workspace selection, or --json.

Non-interactive and JSON use

lpm run build --filter web --fail-if-no-match --json
lpm run lint test --no-bail --json

Task commands control their own prompts. Use their non-interactive flags after -- where necessary. --fail-if-no-match makes an empty workspace selection fail, which catches misspelled filters in CI.

With --json, child output and cache logs go to stderr. Stdout contains one result object.

Each task includes name, success, cached, skipped, and duration_ms. Failures can also include exit_code and phase. Logs and skip reasons are not embedded in task entries.

The workspace package count includes members added through ^task expansion. It excludes selected members without the requested task. An empty selection without --fail-if-no-match returns a successful result with zero packages.

Shortcuts and hidden scripts

lpm typecheck
lpm run .build

An unknown top-level command can select a script or task with the same name. Built-in commands take precedence. For example, lpm test uses runner detection, while lpm run test selects the task.

Use lpm run for task-runner flags. Arguments after a shorthand name go to the task itself. A shorthand reads the scripts and tasks of the current directory only. From a subdirectory, use lpm run, which finds the nearest project. If no script or task matches, shorthand tries a project-local executable. Path-like commands use the source-file runner.

A package script whose name starts with . is a hidden helper. Direct calls such as lpm run .build fail. Visible scripts and task dependencies can call it. Hidden scripts do not appear in script listings or missing-script suggestions.

Troubleshooting

Flags

The global flags include --json.

See also

• lpm dev — development servers and services
• lpm exec — local executables and source files
• lpm test — test-runner detection
• Task runner — task configuration and dependencies
• Workspaces — selection and dependency graphs