Command Line Options

lage is meant to be run as a CLI. After installing lage inside the repository or globally, you can run the npm scripts from your repository like this:

lage [options] <command>

---

Run Command

Runs a set of commands in a target graph. The targets are defined by packages and their scripts as defined the package.json files.

Usage: lage [run] <command1> [command2...commandN] [options] run commands

Options

Logging options also apply.

Filtering options

These can optionally be set with environment variables LAGE_FILTER_* (e.g. LAGE_FILTER_SCOPE).

--scope <scope...>         scopes the run to a subset of packages (by default, includes the dependencies and dependents as well)
--no-deps|--no-dependents  disables running any dependents of the scoped packages (env: LAGE_FILTER_NO_DEPS)
--include-dependencies     adds the scoped packages dependencies as the "entry points" for the target graph run
   |--dependencies           (env: LAGE_FILTER_INCLUDE_DEPENDENCIES)
--to <scope...>            runs up to a package (shorthand for --scope=<scope...> --no-dependents)
--since <since>            only runs packages that have changed since the given commit, tag, or branch
--ignore <ignore...>       ignores files when calculating the scope with `--since` in addition to the files specified in lage.config.js
--grouped                  groups the logs (default: false)

Worker options

These can optionally be set with environment variables LAGE_POOL_* (e.g. LAGE_POOL_CONCURRENCY).

-c|--concurrency <number>           max jobs to run at a time
--max-workers-per-task <values...>  set max worker per task, e.g. --max-workers-per-task build=2 test=4

Other options

These can optionally be set with environment variables LAGE_RUN_* (e.g. LAGE_RUN_NODE_ARG).

-n|--node-arg <arg>     node arguments for workers and child processes (like NODE_OPTIONS) as a single string
                          (e.g. --nodearg="--max_old_space_size=1234 --heap-prof")
--no-cache              disables the cache (env: LAGE_RUN_CACHE)
--reset-cache           resets the cache, filling it after a run
--skip-local-cache      skips caching locally (defaults to true in CI environments)
--profile [profile]     writes a run profile into a file that can be processed by Chromium devtool
--continue              continues the run even on error
--allow-no-target-runs  succeed even if no targets match the given name
--watch                 runs in watch mode

Examples

Basic case, running "build", "test", and "lint" against all packages

lage build test lint

Concurrency

lage build test lint --concurrency=4

Filtering by certain packages

Scoped to "package-a" and "package-b" and their dependencies and dependents:

lage build test lint --scope package-a package-b

Scoped to "package-a" and "package-b" only:

lage build test lint --scope package-a package-b --no-deps

Scoped to packages that have changed in the current branch against a target merge branch:

lage build test lint --since origin/master

Providing node.js arguments for each command

lage build test lint --nodearg=--max_old_space_size=1234 --nodearg=--heap-prof

Continue running even after encountering an error for one of the targets

lage build test lint --continue

Controlling logged outputs

Show verbose output for each target:

lage build test lint --verbose

Show only errors for each target:

lage build test lint --log-level=error

Show logs as grouped by each target:

lage build test lint --grouped --verbose

Choosing a different reporter while logging (e.g. nice outputs for Azure DevOps):

lage build test lint --reporter=azureDevops

Or combine multiple reporters (e.g. Azure DepOps with VerboseFileLog)

lage build test lint --reporter azureDevops --reporter vfl --log-file /my/verbose/log.file

Ignoring files when calculating the scope with --since in addition to files specified in lage.config:

lage build test lint --since origin/master --ignore "package.json" "yarn.lock" "/.azure-pipelines/"

---

Cache Command

lage by default will skip tasks that it has already done recently. As long as the source file and the command called to lage has not changed, those packages will be skipped. Sometimes, this incremental behavior is not desired. You can override the caching behavior by using the no-cache argument.

lage build --no-cache

Options

Logging options also apply.

--prune <days>            Prunes cache older than certain number of <days>
--clear                   Clears the cache locally

Examples

Prune local cache older than 30 days

lage cache --prune 30

Completely clear all local cache

lage cache --clear

---

Common options

Logging options

Logging options apply to most commands, and can optionally be set with environment variables LAGE_LOGGER_* (e.g. LAGE_LOGGER_REPORTER).

--reporter <reporter...>  reporter (choices: "default", "json", "azureDevops", "npmLog", "verboseFileLog", "vfl")
--log-level <level>       log level (choices: "info", "warn", "error", "verbose", "silly")
--log-file <file>         when used with --reporter vfl, writes verbose, ungrouped logs to the specified file
--progress                show progress (default: true locally, false in CI)
--verbose                 verbose output (default: false)
--grouped                 groups the logs by package+task (default: false)
--indented                enabled indentation of the JSON output (default: false)

Verbosity

lage by default will hide the output from successful tasks. If you want to see all output as it's generated, use --verbose:

lage build --verbose

You can also control the log level more specifically with --log-level <level>. This example will show warn messages and above (error):

lage build --log-level warn

Valid values are silly, verbose, info, warn, error. If error is passed to --log-level, you'll receive the least amount of information. The default is info.

Grouping

By default, lage will interweave all the stdout and stderr from all active targets as they are running.

The --grouped option can be used to group messages by target (package). The messages will only be displayed when the target is completed.

lage build --verbose --grouped

Reporter

lage comes with various reporters which take the logged messages of the target runs, format them, and display them.

You can pick the reporter by passing the --reporter flag. This can be specified more than once, though it only makes sense to have a single reporter for console logging (others could log to a file).

lage build --reporter json

Available reporters:

Name	Internal class	Description
default/not specified	BasicReporter or LogReporter	Usually if running in an interactive terminal, shows progress but not the names of currently running targets (unless progress is disabled or verbose or grouped are enabled). Otherwise, uses npmLog.
fancy	ProgressReporter	Shows progress including the names of currently running targets, but is slower. This was the default in v2 prior to 2.14.16.
npmLog (old)	LogReporter	This is the reporter from lage v1. It logs tasks without progress info.
azureDevops (adoLog)	AdoReporter	Logs tasks
json	JsonReporter	Write logs to the console in JSON format
verboseFileLog (vfl)	VerboseFileLogReporter	Writes to a file specified with --log-file
profile	ChromeTraceEventsReporter	Writes a Chrome dev tools profile file. Typically enabled with --profile (use --profile=filename to customize the name).

Custom reporters

You can also create and use your own custom reporters. Define them in your lage.config.js:

/** @type {import("lage").ConfigFileOptions} */
const config = {
  reporters: {
    myReporter: "./reporters/my-custom-reporter.js"
  }
};
module.exports = config;

The passed-in javascript file must be from a proper ESM module or .mjs file.

Then use them with the --reporter flag:

lage build --reporter myReporter

You can also combine multiple reporters:

lage build --reporter json --reporter myReporter