Running tasks

Run task <name> from your project to execute a task. With no name, Task runs the default task. Start by listing tasks, then run one:

task --list
task build

--list shows tasks with descriptions. Use --list-all to include tasks without descriptions; internal tasks remain hidden. See Defining tasks to create these entries.

Pass several names, such as task lint test, to run them in order. Use --parallel for independent tasks that can run concurrently. To pass values or command arguments, see Command-line arguments.

Preview commands

Use --dry (or -n) to print the commands Task would run:

task --dry build

Task still resolves templates and dynamic variables while preparing the commands. A variable declared with sh can therefore execute its shell command during a dry run. See Variables.

Run from a subdirectory

If Task cannot find a Taskfile in the current directory, it searches parent directories. Tasks run from the directory containing that Taskfile unless their dir setting changes it.

Use {{.USER_WORKING_DIR}} when the task should act on the directory where you invoked it. In a monorepo, this lets each service use the same task to start its Docker Compose services:

version: '3'

tasks:
  up:
    dir: '{{.USER_WORKING_DIR}}'
    preconditions:
      - test -f docker-compose.yml
    cmds:
      - docker compose up -d

From a service directory containing docker-compose.yml, run task up. The root Taskfile supplies the task; the service directory supplies its files.

Use a personal Taskfile

Store a Taskfile in your home directory and use --global (or -g) to call it from anywhere:

task --global from-working-directory

Global tasks run in your home directory by default. Set dir to {{.USER_WORKING_DIR}} when a personal utility should work on the current project:

version: '3'

tasks:
  from-home:
    cmds:
      - pwd

  from-working-directory:
    dir: '{{.USER_WORKING_DIR}}'
    cmds:
      - pwd

Read a Taskfile from stdin

Use --taskfile - (or -t -) to read a generated Taskfile from standard input. For example, to read an existing file through stdin:

task --taskfile - < ./Taskfile.yml

You can also pipe the output of a Taskfile generator into task --taskfile -. With no task name, these commands run the generated file's default task.

Run a terminal app

Set interactive: true on a task that launches a terminal application:

version: '3'

tasks:
  edit:
    interactive: true
    cmds:
      - vim my-file.txt

Run task edit to open the editor. Interactive applications need direct access to the terminal; buffered or prefixed output modes and other tasks running concurrently can interfere with their input and display.

This task setting is distinct from the CLI --interactive option, which prompts for missing variables.

Choose a file name

Use --taskfile to choose a specific file or --dir to run in another project:

task --taskfile Taskfile.ci.yml build
task --dir ./backend build

Task looks for these names in order of priority:

• Taskfile.yml
• taskfile.yml
• Taskfile.yaml
• taskfile.yaml
• Taskfile.dist.yml
• taskfile.dist.yml
• Taskfile.dist.yaml
• taskfile.dist.yaml

Commit a .dist variant if users need to supply their own Taskfile.yml override. The local file takes priority; add it to .gitignore if it should remain personal.