Every devlanes command and option with its help text; devlanes <command> --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.
devlanes [OPTIONS] [COMMAND]
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).
Accepted by every command, before or after the command name.
--json: Print JSON: one document, or NDJSON for streams (same as --output json)--output <MODE>: 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 <PROJECT>: Use this project instead of the one containing the current directory [env: DEVLANES_PROJECT]--file <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 <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 <KEY=VALUE>: Set a variable for started processes (start, restart, run TASK, exec); repeatable--timeout <DURATION>: Limit waits and streams, such as 30s, 5m or 1h [default for start and wait: 180s]--budget <BYTES>: 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]
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.
devlanes start [OPTIONS] [UNIT]...
[UNIT]...: Units to start ([lane:]unit, globs, +tag) [default: what the lane ran before, else its default profile]--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
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
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.
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 <DIR>: Write each unit's log of this run to DIR as text files, for CI artifacts
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.
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
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.
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
Show lanes and units with state, ports, URLs, CPU and memory
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
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.
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 <N>: Show the last N lines [default: 100 in agent mode or without a terminal]--head <N>: Show the first N lines of the selected range-f, --follow: Keep streaming new lines; agent mode requires --timeout--since <WHEN>: Only lines newer than a duration (5m), a time in milliseconds, or start (the lane's last start)--grep <REGEX>: Only lines matching this regular expression--level <LEVEL>: Only lines at this level or above: debug, info, warn or error--around <CURSOR>: Show the lines around this cursor, such as api#120-C, --context <N>: Lines before and after --around Default:3.--cursor <CURSOR>: Continue after this cursor, as printed by an earlier logs call--mine: Only units this agent session started
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
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].
devlanes wait [OPTIONS] [TARGET]
[TARGET]: Unit ([lane:]unit) or lane ([project@]lane) to wait for [default: pick from a list]
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.
devlanes with [OPTIONS] [UNIT]... -- <COMMAND>...
[UNIT]...: Units to start ([lane:]unit, globs, +tag) [default: what the lane ran before, else its default profile]--profile <PROFILE>: Start the units of this profile from devlanes.yaml; repeat to combine profiles (later ones win on env)--logs-dir <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>...: Command and arguments to run once the lane is ready
Examples:
devlanes with -- pnpm test
devlanes with --profile e2e -- pnpm test:e2e
devlanes with api --logs-dir devlanes-logs -- cargo test --test api
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.
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
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.
devlanes exec [OPTIONS] --name <NAME> -- <COMMAND>...
--name <NAME>: Unit name for the command, used by logs, stop and attach--no-pty: Use pipes instead of a pseudoterminal<COMMAND>...: Command and arguments to run
Attach this terminal to a unit's terminal; C-a d detaches
devlanes attach [OPTIONS] [UNIT]
[UNIT]: Unit to attach to ([lane:]unit) [default: pick from a list]
Open the TUI; closing it never stops anything
devlanes ui [OPTIONS]
Create, list, clean and resume worktree lanes
devlanes lane [OPTIONS] <COMMAND>
List lanes, including moved, unassigned and missing ones
devlanes lane ls [OPTIONS]
Add another lane for the current folder. It has its own index, ports
and domain, and --lane <name> or --lane <index> 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 <path> <branch>
and run devlanes start in it.
Without --start, a terminal asks whether to start the new lane right away.
devlanes lane new [OPTIONS]
--name <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
Stop a lane, run its clean tasks and teardown, delete its data and logs, and free its ports (needs --yes)
devlanes lane clean [OPTIONS] [LANE]
[LANE]: Lane to clean ([project@]lane) [default: pick from a list]
Clean lanes whose worktree or project file is gone or names another project, and drop unused port offsets (needs --yes)
devlanes lane gc [OPTIONS]
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.
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
Explain failures: why a unit is not up, errors, events and resource use
devlanes debug [OPTIONS] <COMMAND>
Explain why a unit is not running or not ready, with a fix for each reason
devlanes debug why [OPTIONS] [UNIT]
[UNIT]: Unit to explain ([lane:]unit) [default: pick from a list]
List failed units, crash counts, recent error lines and port conflicts
devlanes debug errors [OPTIONS]
--since <DURATION>: Count crashes and error lines from this long ago, such as 5m or 2h [default: all recorded runs]
Print the daemon's event stream: lane, unit, task and port events
devlanes debug events [OPTIONS]
-f, --follow: Keep streaming until interrupted [default: print recent events]
Show CPU and memory per lane and unit
devlanes debug top [OPTIONS]
Freeze this lane's processes and own containers now, as if it had been idle for lanes.freeze_after
devlanes debug freeze [OPTIONS] [LANE]
[LANE]: Lane to freeze ([project@]lane) [default: the current lane]
Resume a throttled or frozen lane
devlanes debug thaw [OPTIONS] [LANE]
[LANE]: Lane to thaw ([project@]lane) [default: the current lane]
Print the lane's project config as YAML after merging its files and templates; expressions stay unevaluated
devlanes debug config [OPTIONS]
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.
devlanes debug bundle [OPTIONS] [-- <ARGS>...]
--to <PATH>: Write the archive here [default: devlanes-debug-.tar.gz in the temporary directory]--log-lines <N>: Lines of the daemon's log to include Default:500.[ARGS]...: devlanes arguments to run again with -vv and include, such as: -- start api
Examples:
devlanes debug bundle
devlanes debug bundle --to bug.tar.gz -- start api
Show, export or enter the environment of a lane or unit
devlanes env [OPTIONS] <COMMAND>
Print the environment of the lane or of one unit as KEY=VALUE lines
devlanes env show [OPTIONS] [UNIT]
[UNIT]: Unit whose environment to print ([lane:]unit) [default: the lane's variables]--explain: Show where each variable comes from; secret values are hidden
Print export KEY=VALUE lines for eval in a shell
devlanes env export [OPTIONS] [UNIT]
[UNIT]: Unit whose environment to export ([lane:]unit) [default: the lane's variables]--shell <SHELL>: Shell syntax of the printed lines Values:posix(export NAME='value', for sh, bash, zsh and Git Bash),pwsh($env:NAME = 'value', for Windows PowerShell 5.1 and PowerShell 7; the lines are ASCII and other text is decoded from Base64). Default:posix.
Examples:
eval "$(devlanes env export api)"
devlanes env export api --shell pwsh | Out-String | Invoke-Expression
Windows PowerShell 5.1 and PowerShell before 7.5 remove a variable that is
assigned an empty value, so variables with empty values end up unset there.
Open a subshell with the lane's or one unit's environment
devlanes env shell [OPTIONS] [UNIT]
[UNIT]: Unit whose environment to use ([lane:]unit) [default: the lane's variables]
Print, open and list service URLs and routed hostnames
devlanes url [OPTIONS] <COMMAND>
Print a service's URL, for scripts
devlanes url print [OPTIONS] [UNIT]
[UNIT]: Service whose URL to print ([lane:]unit) [default: pick from a list]
Open a service's URL in the browser; agent mode only prints it
devlanes url open [OPTIONS] [UNIT]
[UNIT]: Service to open ([lane:]unit) [default: pick from a list]
List routed hostnames with their lane, unit, port and state
devlanes url ls [OPTIONS]
Start, stop and inspect the project's containers
devlanes infra [OPTIONS] <COMMAND>
Start shared and per-lane containers and wait until they are healthy
devlanes infra up [OPTIONS]
Stop the project's shared containers; their data is kept
devlanes infra down [OPTIONS]
Show the containers' health and ports
devlanes infra status [OPTIONS]
Print a container's Docker logs; replicas of a compose service are merged
devlanes infra logs [OPTIONS] <CONTAINER>
<CONTAINER>: Compose service or infra.containers name-n, --tail <N>: Show the last N lines Default:200.-f, --follow: Keep streaming new lines, also across container restarts; agent mode requires --timeout
Validate devlanes.yaml, or read and change the user config.yaml.
check validates the project's devlanes.yaml in this worktree. get, set and
unset act on the user config.yaml in the devlanes home (~/.devlanes, or
$DEVLANES_HOME), the settings this machine shares across projects; they work
without the daemon.
devlanes config [OPTIONS] <COMMAND>
Examples:
devlanes config check validate this worktree's devlanes.yaml
devlanes config get every user setting, defaults included
devlanes config get proxy.https_port
devlanes config set tui.theme dark
devlanes config set tls.trust '[system, firefox]'
devlanes config unset tui.theme back to the default
Validate this worktree's devlanes.yaml, including preset options
devlanes config check [OPTIONS]
Print a setting of the user config.yaml with defaults included; without a key, every setting
devlanes config get [OPTIONS] [KEY]
[KEY]: Dotted setting or section, such as tui.theme or proxy [default: the whole config]
Change a setting in the user config.yaml, keeping its comments; refuses invalid values
devlanes config set [OPTIONS] <KEY> <VALUE>
<KEY>: Dotted setting, such as tui.theme or proxy.https_port<VALUE>: New value, read as YAML: true, 443, dark, 30d or [system, firefox]
Remove a setting from the user config.yaml so its default applies again
devlanes config unset [OPTIONS] <KEY>
<KEY>: Dotted setting or section, such as tui.theme
Trust the devlanes CA and set up hostnames for this machine; asks once.
Works out what this machine needs and lists each step as ok, todo or skip: ca trust the CA in the stores tls.trust names (mkcert's CA with tls.ca: mkcert) hosts install the /etc/hosts helper (macOS and Linux) when *.localhost does not resolve to loopback, the user config asks for the hosts file, or the daemon needs it for a project resolver send hostnames.tld to the devlanes DNS server (a resolver file, or an NRPT rule on Windows) when hostnames.resolver is resolver
Then it asks once before doing the todo steps; sudo asks for your password at most once. Without a terminal, pass --yes.
devlanes setup [OPTIONS]
--check: Only report each step; exit 0 when nothing is missing, 1 otherwise--remove: Undo everything: the resolver file or NRPT rule, the /etc/hosts helper and the CA trust--keep-ca: With --remove, keep the CA trusted
Examples:
devlanes setup set up what is missing, asking once
devlanes setup --check exit 1 when something is missing
devlanes setup --remove --keep-ca remove the hosts helper and resolver, keep the CA
Install the latest devlanes release the way devlanes was installed, then restart the daemon.
Checks for a newer release, asks once (a minor release before 1.0 may break what worked, so it lists those changes and defaults to no), installs it, and restarts the daemon, which starts again the lanes that were running. install.sh, install.ps1 and standalone binaries download the release archive and check it against the release's SHA256SUMS; npm, pnpm, Bun, Yarn, uv, pipx and Homebrew installs run their package manager. Other installs, such as cargo or a project's own dependency, print the command to run instead. Without a terminal, pass --yes. A build of main, installed with install.sh --channel next or install.ps1 -Channel next, updates to the latest build of main.
devlanes update [OPTIONS]
--check: Only check: show the install method, the running and latest versions and what changed
Examples:
devlanes update install the latest release, asking first
devlanes update --yes install it without asking
devlanes update --check show the latest release and what changed
Remove devlanes from this machine: stop the daemon, then remove its login service, what devlanes setup changed and this install.
In order, and going on when a step fails:
- stop the daemon (asked once up front, naming the processes it stops; without a terminal, pass --yes)
- remove the login service (daemon install)
- undo devlanes setup: the CA trust, the /etc/hosts helper and the resolver file or NRPT rule; sudo asks for your password at most once
- remove this install: install.sh and install.ps1 files (and the user PATH entry on Windows), or the package manager's remove command. A project's own dependency and a source build stay.
- the devlanes home (~/.devlanes, or $DEVLANES_HOME) and lane data: listed with their sizes and deleted only if you answer yes to a second question. With --yes and no terminal they stay unless --remove-data is given.
devlanes uninstall [OPTIONS]
--remove-data: Delete the devlanes home and lane data without asking--keep-data: Keep the devlanes home and lane data, and print where they are--dry-run: Print what each step would remove; change nothing
Examples:
devlanes uninstall --dry-run show what would be removed
devlanes uninstall remove devlanes, asking first and again before deleting data
devlanes uninstall --yes --keep-data
Connect to boxes and mirror their lanes here
devlanes remote [OPTIONS] <COMMAND>
Connect to a box and mirror its lanes, ports and hostnames here
devlanes remote connect [OPTIONS] <HOST>
<HOST>: Box name from remote.boxes in the user config, or an SSH destination--background: Return once connected instead of staying attached for prompts--code <CODE>: One-time pairing code from devlanes daemon pair on the box
Disconnect from a box and remove its mirrored ports and hostnames
devlanes remote disconnect [OPTIONS] [HOST]
[HOST]: Box to disconnect [default: every box]
List known boxes and their connection state
devlanes remote ls [OPTIONS]
List the synced folders of running lanes
devlanes remote sync [OPTIONS]
Choose which box serves a lane that clashes with others.
Lanes clash when their hostnames overlap. The same lane on two boxes always clashes,
as on forks of one box image. This machine mirrors one of them. A lane running here
comes first, then the chosen box lane, then a stopped lane here, then the box connected
first. The latest choice wins and deletes the choices it clashes with. A choice stays
until another one replaces it, devlanes remote disconnect forgets the box, or a lane
here that clashes with it starts. A box that is not connected can be chosen too.
--local gives the hostnames back to this machine's lane.
devlanes remote use <BOX> <LANE>
devlanes remote use --local <LANE>
<BOX>: Box whose lane serves the hostnames<LANE>: Lane reference, such as acme@0--local <LANE>: Give the lane's hostnames back to this machine
Examples:
devlanes remote use fork-b acme@0
devlanes remote use --local acme@0
Run, stop and install the background daemon, and pair other machines with it
devlanes daemon [OPTIONS] <COMMAND>
Start the daemon in the background unless it already runs, then show its status
devlanes daemon start [OPTIONS]
Show the daemon's version, pid, uptime and managed process count; never starts it
devlanes daemon status [OPTIONS]
Stop the daemon and every process it manages
devlanes daemon stop [OPTIONS]
Restart the daemon and start again, with this shell's environment, the services that ran; asks first when processes are running
devlanes daemon restart [OPTIONS]
Print the daemon's own log file
devlanes daemon logs [OPTIONS]
-f, --follow: Keep printing new lines--tail <N>: Lines to show [default: 100]
Install a login service so the daemon starts at login and outside agent sandboxes
devlanes daemon install [OPTIONS]
Remove the login service; a running daemon keeps running
devlanes daemon uninstall [OPTIONS]
Stop everything and empty the state database; lanes get new numbers and ports (needs --yes)
devlanes daemon reset-state [OPTIONS]
Print a one-time code that pairs another machine with this one
devlanes daemon pair [OPTIONS]
List the machines paired or connected to this one
devlanes daemon clients [OPTIONS]
Disconnect a client and delete its pairing
devlanes daemon revoke [OPTIONS] <CLIENT>
<CLIENT>: Client name or id, as devlanes daemon clients shows it
Check the daemon, Docker, proxy, CA, hosts file and output mode, each with a fix; never starts the daemon
devlanes doctor [OPTIONS]
Print shell completions; lane and unit names come from the running daemon
devlanes completions [OPTIONS] <SHELL>
<SHELL>: Shell to generate completions for Values:bash,elvish,fish,powershell,zsh.