--- title: "CLI reference" url: https://devlanes.run/docs/reference/cli/ description: "Every devlanes command and option with its help text; devlanes --help prints the same." updated: 2026-11-02T00:18:06.000Z --- # CLI reference Every `devlanes` command and option with its help text; `devlanes --help` prints the same. Run a dev environment per git worktree, side by side. Every worktree of a project is a lane with its own ports, hostnames such as web.acme2.localhost and environment, so branches run at the same time. A per-user daemon owns the processes and containers and keeps them running when the terminal closes; this command and the TUI are its clients. Without a command, devlanes opens the TUI on a terminal and prints status otherwise. ```text devlanes [OPTIONS] [COMMAND] ``` ```text Examples: devlanes start bring up this worktree's lane devlanes status lanes and units of this project devlanes logs acme@2:api --tail 200 last 200 lines of api in lane 2 devlanes with --profile e2e -- pnpm test:e2e start, run the tests, stop devlanes stop --mine stop what this agent session started References: A lane is [project@]lane: a lane number (2), a branch (feat/checkout), a lane or worktree directory name, or a path. Without project@ the project of the current directory is used. A unit is [lane:]unit, such as api, 2:api or acme@feat/checkout:web. Commands that take several units also accept globs ("api-*") and tags (+web). ``` ## Global options Accepted by every command, before or after the command name. - `--json`: Print JSON: one document, or NDJSON for streams (same as --output json) - `--output `: Output mode [default: agent when an AI agent runs devlanes, plain in CI or without a terminal, else human] Values: `human` (Colors and symbols, for a terminal), `plain` (The same information without color, one line per event), `agent` (Terse lines for AI agents: failures first, with next commands, size-capped), `json` (The daemon's data as JSON, or NDJSON for streams). - `-p, --project `: Use this project instead of the one containing the current directory [env: DEVLANES_PROJECT] - `--file `: Use this project file instead of the nearest devlanes.yaml (for example devlanes.prod.yaml); after the first use, -p finds its project - `--lane `: Use this lane ([project@]lane) instead of the current worktree's - `--yes`: Confirm actions that would ask first; needed when no terminal can prompt - `--quiet`: Print nothing on success; errors still go to stderr - `--env `: Set a variable for started processes (start, restart, run TASK, exec); repeatable - `--timeout `: Limit waits and streams, such as 30s, 5m or 1h [default for start and wait: 180s] - `--budget `: Cap agent-mode output at this many bytes [default: 16384, minimum: 256] - `-v, --verbose`: Print timestamped diagnostics of the client and daemon to stderr; -vv for more. A bare devlanes -v prints the version [env: DEVLANES_VERBOSE=1|2] ## Commands ### devlanes start Bring up a lane: infra, setup, tasks and services, then wait until ready. Starts the lane of the current worktree, or only the named units. Units that already run are left alone, so starting twice is safe. Waits until every started unit is ready or one fails; Ctrl-C detaches and leaves everything running. Without units or --profile it brings back the services the lane ran before, such as after a reboot or daemon crash. A lane stopped with devlanes stop has nothing to bring back and starts its default profile; start.restore: false in ~/.devlanes/config.yaml always does that. ```text devlanes start [OPTIONS] [UNIT]... ``` - `[UNIT]...`: Units to start ([lane:]unit, globs, +tag) [default: what the lane ran before, else its default profile] - `--profile `: Start the units of this profile from devlanes.yaml; repeat to combine profiles (later ones win on env) - `--attach`: Run the start in the TUI even when DEVLANES_NO_UI or tui.open_on_start turn that off [default on a terminal] - `--no-ui`: Print the start as text instead of running it in the TUI - `--all-at-once`: Start every selected service immediately, bypassing the machine-wide start gate for this run ```text Examples: devlanes start what this worktree's lane ran before (its default profile after devlanes stop) devlanes start api web only these services devlanes start --profile e2e the units of the e2e profile devlanes start 2:+api --timeout 5m units tagged api in lane 2 ``` ### devlanes stop Stop units, or the whole lane when none are named. Stopped services are left out of what a plain devlanes start brings back. A whole-lane stop also forgets the lane's profiles, so its next plain start uses the default profile. ```text devlanes stop [OPTIONS] [UNIT]... ``` - `[UNIT]...`: Units to stop ([lane:]unit, globs, +tag) [default: the whole lane] - `--mine`: Only stop units this agent session started; with no units, across every lane - `--logs-dir `: Write each unit's log of this run to DIR as text files, for CI artifacts ### devlanes restart Stop and start units again with a fresh environment, or the whole lane when none are named. A whole-lane restart stops everything, keeps the lane's saved profiles and services, and starts it again as a plain devlanes start does: infra, setup, tasks, services and any port change in the project file. ```text devlanes restart [OPTIONS] [UNIT]... ``` - `[UNIT]...`: Units to restart ([lane:]unit, globs, +tag) [default: the whole lane] - `--all-at-once`: Start every selected service immediately, bypassing the machine-wide start gate for this run - `--no-ui`: Print the restart as text instead of running it in the TUI ### devlanes reload Apply project file and .env changes to the running lane. Stops the units the file removed, restarts the ones it changed and starts the ones it added. Without units, a change to infra or ports restarts the whole lane instead. With units, it applies only their changes. devlanes status shows what changed. ```text devlanes reload [OPTIONS] [UNIT]... ``` - `[UNIT]...`: Apply only these units' changes ([lane:]unit) [default: every change in the lane] - `--all-at-once`: Start every selected service immediately, bypassing the machine-wide start gate for this run - `--no-ui`: Print the reload as text instead of running it in the TUI ### devlanes status Show lanes and units with state, ports, URLs, CPU and memory ```text devlanes status [OPTIONS] [LANE] ``` - `[LANE]`: Lane to show ([project@]lane) [default: every lane of the current project] - `--watch`: Keep printing lane changes until interrupted - `--mine`: Only show units this agent session started ### devlanes logs Read unit logs; each line carries a cursor to continue from. Lines of several units are merged by time. Each line starts with a cursor such as api#120 that --cursor and --around accept. In agent mode and without a terminal the output defaults to the last 100 lines within the output budget. ```text devlanes logs [OPTIONS] [UNIT]... ``` - `[UNIT]...`: Units to read ([lane:]unit, globs, +tag) [default: pick from a list] - `--all`: Read every unit of the lane, grouped by unit - `--tail `: Show the last N lines [default: 100 in agent mode or without a terminal] - `--head `: Show the first N lines of the selected range - `-f, --follow`: Keep streaming new lines; agent mode requires --timeout - `--since `: Only lines newer than a duration (5m), a time in milliseconds, or start (the lane's last start) - `--grep `: Only lines matching this regular expression - `--level `: Only lines at this level or above: debug, info, warn or error - `--around `: Show the lines around this cursor, such as api#120 - `-C, --context `: Lines before and after --around Default: `3`. - `--cursor `: Continue after this cursor, as printed by an earlier logs call - `--mine`: Only units this agent session started ```text Examples: devlanes logs api --tail 200 devlanes logs acme@2:api --since 5m --grep 'timeout|refused' devlanes logs api -f --timeout 30s devlanes logs --all --since start ``` ### devlanes wait Wait until a unit or lane is ready or failed. Exits 0 when ready, 1 when it failed (with the reason and log tail) and 124 when --timeout passes first [default: 180s]. ```text devlanes wait [OPTIONS] [TARGET] ``` - `[TARGET]`: Unit ([lane:]unit) or lane ([project@]lane) to wait for [default: pick from a list] ### devlanes with Start the lane, run a command against it, then stop what was started. Waits for ready first; when a unit fails it prints the failure and exits 1 without running the command. The command gets the lane's environment, including DEVLANES_PUBLIC_URL_ for every service, plus NODE_EXTRA_CA_CERTS, DENO_CERT, SSL_CERT_FILE and REQUESTS_CA_BUNDLE for the devlanes CA unless the shell sets them. Afterwards devlanes writes --logs-dir, prints each unit's state, run time and average and peak CPU and memory when output is not a terminal (CI logs, pipes) and adds the same table to the GitHub step summary, stops what it started (and the daemon, if it started it) and exits with the command's exit code. ```text devlanes with [OPTIONS] [UNIT]... -- ... ``` - `[UNIT]...`: Units to start ([lane:]unit, globs, +tag) [default: what the lane ran before, else its default profile] - `--profile `: Start the units of this profile from devlanes.yaml; repeat to combine profiles (later ones win on env) - `--logs-dir `: Write every unit's log of the run to DIR as text files, for CI artifacts - `--keep`: Leave the lane running afterwards, for debugging - `--all-at-once`: Start every selected service immediately, bypassing the machine-wide start gate for this run - `...`: Command and arguments to run once the lane is ready ```text Examples: devlanes with -- pnpm test devlanes with --profile e2e -- pnpm test:e2e devlanes with api --logs-dir devlanes-logs -- cargo test --test api ``` ### devlanes run Run a task from devlanes.yaml and exit with its exit code. The task's output streams to this terminal. Ctrl-C asks before stopping a foreground task on a terminal and stops it in agent mode. Tasks with confirm: need --yes when no terminal can prompt. ```text devlanes run [OPTIONS] [TASK] ``` - `[TASK]`: Task to run, as named under tasks: in devlanes.yaml, or one infra entry as infra.setup.NAME or infra.teardown.NAME [default: pick from a list] - `--list`: List the tasks and the script sources they use - `--detach`: Start the task in the background and return ### devlanes exec Run an ad-hoc command as a unit of the lane instead of backgrounding it with &. The daemon owns the process: logs, stop, attach and status work on it by its --name, and it gets the lane's environment. ```text devlanes exec [OPTIONS] --name -- ... ``` - `--name `: Unit name for the command, used by logs, stop and attach - `--no-pty`: Use pipes instead of a pseudoterminal - `...`: Command and arguments to run ### devlanes attach Attach this terminal to a unit's terminal; C-a d detaches ```text devlanes attach [OPTIONS] [UNIT] ``` - `[UNIT]`: Unit to attach to ([lane:]unit) [default: pick from a list] ### devlanes ui Open the TUI; closing it never stops anything ```text devlanes ui [OPTIONS] ``` ### devlanes lane Create, list, clean and resume worktree lanes ```text devlanes lane [OPTIONS] ``` ### devlanes lane ls List lanes, including moved, unassigned and missing ones ```text devlanes lane ls [OPTIONS] ``` ### devlanes lane new Add another lane for the current folder. It has its own index, ports and domain, and `--lane ` or `--lane ` addresses it. Commands run in the folder keep using the folder's first lane. For a lane on another branch, create a worktree with `git worktree add ` and run `devlanes start` in it. Without --start, a terminal asks whether to start the new lane right away. ```text devlanes lane new [OPTIONS] ``` - `--name `: Name of the extra lane for this folder, used by `--lane` [default: -] - `--start`: Start the new lane right away - `--no-ui`: With --start, print the start as text instead of running it in the TUI ### devlanes lane clean Stop a lane, run its clean tasks and teardown, delete its data and logs, and free its ports (needs --yes) ```text devlanes lane clean [OPTIONS] [LANE] ``` - `[LANE]`: Lane to clean ([project@]lane) [default: pick from a list] ### devlanes lane gc Clean lanes whose worktree or project file is gone or names another project, and drop unused port offsets (needs --yes) ```text devlanes lane gc [OPTIONS] ``` ### devlanes lane resume Start the lanes that were running before a reboot or daemon restart. The daemon never stores a shell's environment, so after a restart each lane needs one start or resume from a shell. A plain start brings back only its own lane; resume uses this shell's environment for every lane that was not stopped by hand, and starts the services each one ran. ```text devlanes lane resume [OPTIONS] ``` - `--all-at-once`: Start every selected service immediately, bypassing the machine-wide start gate for this run - `--no-ui`: Print the starts as text instead of running them in the TUI ### devlanes debug Explain failures: why a unit is not up, errors, events and resource use ```text devlanes debug [OPTIONS] ``` ### devlanes debug why Explain why a unit is not running or not ready, with a fix for each reason ```text devlanes debug why [OPTIONS] [UNIT] ``` - `[UNIT]`: Unit to explain ([lane:]unit) [default: pick from a list] ### devlanes debug errors List failed units, crash counts, recent error lines and port conflicts ```text devlanes debug errors [OPTIONS] ``` - `--since `: Count crashes and error lines from this long ago, such as 5m or 2h [default: all recorded runs] ### devlanes debug events Print the daemon's event stream: lane, unit, task and port events ```text devlanes debug events [OPTIONS] ``` - `-f, --follow`: Keep streaming until interrupted [default: print recent events] ### devlanes debug top Show CPU and memory per lane and unit ```text devlanes debug top [OPTIONS] ``` ### devlanes debug freeze Freeze this lane's processes and own containers now, as if it had been idle for `lanes.freeze_after` ```text devlanes debug freeze [OPTIONS] [LANE] ``` - `[LANE]`: Lane to freeze ([project@]lane) [default: the current lane] ### devlanes debug thaw Resume a throttled or frozen lane ```text devlanes debug thaw [OPTIONS] [LANE] ``` - `[LANE]`: Lane to thaw ([project@]lane) [default: the current lane] ### devlanes debug config Print the lane's project config as YAML after merging its files and templates; expressions stay unevaluated ```text devlanes debug config [OPTIONS] ``` ### devlanes debug bundle Write a redacted archive to attach to a bug report and print its path. The archive holds the client and daemon versions, doctor, config check and status as JSON, the last lines of the daemon's log and, with -- ARGS, the output of devlanes -vv ARGS. Values of secret-looking variables, URL passwords and the home directory are replaced before anything is written; read the files before sending them anyway. ```text devlanes debug bundle [OPTIONS] [-- ...] ``` - `--to `: Write the archive here [default: devlanes-debug-