Use the CLI

Use @runlane/cli for local workers, maintenance, triggers, run inspection, and operator actions. The CLI loads your app runtime. It does not own another task or lane setup.

Install and create the config

npm install --save-dev @runlane/cli
npm exec -- runlane init config \
  --runtime ./src/runlane.ts \
  --runtime-export runlane

This writes runlane.config.ts with the same exported runtime your app uses. The CLI loads TypeScript configs with its packaged tsx loader. Local commands do not need an app prebuild.

The CLI does not load .env files itself. Load them before constructing the runtime, either from your runtime module or the CLI config. See load environment variables for the CLI.

Use --config <path> when the config is not one of the default runlane.config.* files.

Run local development

Run one maintenance pass, drain currently due work, and exit:

npm exec -- runlane dev --once

For a long-lived local process, run:

npm exec -- runlane dev

With a local lane, keep that process running. Commands from another terminal use its control bridge. This keeps them on the same in-memory runtime:

npm exec -- runlane trigger email.send-welcome '{"email":"ada@example.com"}'
npm exec -- runlane runs list

Starting a separate local runtime for each command would create separate in-memory storage, so do not bypass the dev process for local stateful work.

Operate known runs

npm exec -- runlane runs get <run-id> --events
npm exec -- runlane cancel <run-id> --reason customer_request
npm exec -- runlane retry <failed-run-id>
npm exec -- runlane rerun <terminal-run-id>

Add the global --json option for machine-readable output. runlane work starts the configured lane's delivery worker: it polls storage with Local or Postgres polling, and consumes SQS messages with Postgres and SQS. Run runlane tick separately for one maintenance pass. Run maintenance explains production ownership and scheduling.

A command that cannot load the config reports ConfigurationInvalid with the attempted path. Verify the runtime module specifier and export name first. An unknown task means the runtime's named tasks catalog does not contain the requested task id.