Run scripts your project already has
Use this guide when the commands your project runs are already scripts, targets, recipes or tasks in one of its own files, so the command stays written in one place.
Point the service at the script
Section titled “Point the service at the script”Name the file, relative to the project file, and the script in it. The script runs in that file’s folder, the way it does from a terminal there. Tasks take the same two keys.
services: api: run_script: file: apps/api/package.json name: devservicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: dev }. devlanes picks the tool from the file name (package.json, Makefile, justfile, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file's directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. Presets need it to place their flags, and a profile's run_scripts can swap the script name. Exactly one of run and run_script is required after templates are applied.
services.<name>.run_script.fileFile that defines the script, relative to the project file's directory, such as apps/api/package.json. The script runs in this file's directory. Required unless an override or extends child keeps the inherited file.
services.<name>.run_script.nameScript, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.
The file name picks the tool:
package.json: the script, with the package manager the project declares inpackageManageror its lockfile.- A Makefile:
make <target>. - A justfile:
just <recipe>. - A Taskfile (
Taskfile.yml,Taskfile.yaml,Taskfile.dist.ymlorTaskfile.dist.yaml, also in lowercase):task <name>. The task gets a preset’s flags in{{.CLI_ARGS}}. devlanes runstask, so on Arch Linux, where the binary isgo-task, put atasklink to it on yourPATH. Cargo.toml:cargo run --bin <name>, where the name is a binary.pyproject.toml: an entry under[project.scripts], run with uv or Poetry.deno.json:deno task <name>.go.mod:go run ./cmd/<name>, where the name is a folder undercmd..or a name with a/, such astools/seed, is a package path from the go.mod folder.pom.xml: Maven, with the name as the goals and options you would type aftermvn, such asspring-boot:run -Pdev.build.gradle,build.gradle.kts,settings.gradleorsettings.gradle.kts: Gradle, with the name as the tasks and options you would type aftergradle, such as:web:bootRun.
A start checks that the script exists and lists the names the file has when it does not. Maven and Gradle report a goal or task that does not exist themselves, and the service shows as failed.
Run Maven goals and Gradle tasks
Section titled “Run Maven goals and Gradle tasks”devlanes runs the nearest mvnw or gradlew between the file’s folder and the worktree’s root, and mvn or gradle when there is none. Quote an argument that contains spaces, as in a shell:
services: api: run_script: file: pom.xml name: spring-boot:run "-Dspring-boot.run.jvmArguments=-Xmx1g -Dacme.mode=dev"servicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.run_scriptScript to run from a project file, as { file, name }, such as { file: apps/api/package.json, name: dev }. devlanes picks the tool from the file name (package.json, Makefile, justfile, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file's directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. Presets need it to place their flags, and a profile's run_scripts can swap the script name. Exactly one of run and run_script is required after templates are applied.
services.<name>.run_script.fileFile that defines the script, relative to the project file's directory, such as apps/api/package.json. The script runs in this file's directory. Required unless an override or extends child keeps the inherited file.
services.<name>.run_script.nameScript, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.
A profile that swaps a Maven or Gradle name has to repeat the whole name, options included. To run one module of a multi-module Maven build from the root pom, see Run Spring Boot and Quarkus.
Use a plain command for the rest
Section titled “Use a plain command for the rest”A command that is not a script in one of these files goes in run, written as you would type it, with an expression where it needs the port.
services: api: run: uv run uvicorn acme.main:app --host 127.0.0.1 --port ${{ self.port }} --reloadservicesLong-running processes of each lane, started together after infrastructure, setup and lane.start tasks. Each service gets its own port as PORT and, with hosts, HTTPS hostnames. A service that exits shows as failed and is not restarted.
services.<name>A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane's block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.
services.<name>.runCommand that starts the service. A string runs with /bin/sh -c, so pipes, && and multi-line scripts work; a list is an argv run directly without a shell. It starts in the project file's directory unless cwd is set. devlanes runs it exactly as written, so it cannot be combined with preset; prefer run_script when the command is a script in a project file. Exactly one of run and run_script is required after templates are applied. In a list, an item that is one ${{ }} expression giving a number or true/false becomes its text, such as --port followed by ${{ self.port }}.
If a profile should run another script
Section titled “If a profile should run another script”A profile, a named choice of services for a start, can swap the script name for the services that use it, such as a start script in place of the dev server. Share settings and choose which services start shows it.
If only you need a different script
Section titled “If only you need a different script”Your local file, the devlanes.local.yaml that stays out of Git, can change the script name and keep the file. Keep personal changes out of Git covers it.