task/website/src/docs/reference/cli.md

title, description, permalink, outline

title	description	permalink	outline
Command Line Interface Reference	Complete reference for Task CLI commands, flags, and exit codes	/reference/cli/	deep

Command Line Interface Reference

Task has multiple ways of being configured. These methods are parsed, in sequence, in the following order with the highest priority last:

• Environment variables
• Configuration files
• Command-line flags

In this document, we will look at the last of the three options, command-line flags. All CLI commands override their configuration file and environment variable equivalents.

Format

Task commands have the following syntax:

task [options] [tasks...] [-- CLI_ARGS...]

::: tip

If -- is given, all remaining arguments will be assigned to a special CLI_ARGS variable.

:::

Commands

task [tasks...]

Run one or more tasks defined in your Taskfile.

task build
task test lint
task deploy --force

task --list

List all available tasks with their descriptions.

task --list
task -l

task --list-all

List all tasks, including those without descriptions.

task --list-all
task -a

task --init

Create a new Taskfile.yml in the current directory.

task --init
task -i

Options

General

-h, --help

Show help information.

task --help

--version

Show Task version.

task --version

-v, --verbose

Enable verbose mode for detailed output.

task build --verbose

-s, --silent

Disable command echoing.

task deploy --silent

--disable-fuzzy

Disable fuzzy matching for task names. When enabled, Task will not suggest similar task names when you mistype a task name.

task buidl --disable-fuzzy
# Output: Task "buidl" does not exist
# (without "Did you mean 'build'?" suggestion)

Execution Control

-f, --force

Force execution even when the task is up-to-date.

task build --force

-n, --dry

Compile and print tasks without executing them.

task deploy --dry

-p, --parallel

Execute multiple tasks in parallel.

task test lint --parallel

-C, --concurrency <number>

Limit the number of concurrent tasks. Zero means unlimited.

task test --concurrency 4

-x, --exit-code

Pass through the exit code of failed commands.

task test --exit-code

File and Directory

-d, --dir <path>

Set the directory where Task will run and look for Taskfiles.

task build --dir ./backend

-t, --taskfile <file>

Specify a custom Taskfile path.

task build --taskfile ./custom/Taskfile.yml

-g, --global

Run the global Taskfile from $HOME/Taskfile.{yml,yaml}.

task backup --global

Output Control

-o, --output <mode>

Set output style. Available modes: interleaved, group, prefixed.

task test --output group

--output-group-begin <template>

Message template to print before grouped output.

task test --output group --output-group-begin "::group::{{.TASK}}"

--output-group-end <template>

Message template to print after grouped output.

task test --output group --output-group-end "::endgroup::"

--output-group-error-only

Only show command output on non-zero exit codes.

task test --output group --output-group-error-only

-c, --color

Control colored output. Enabled by default.

task build --color=false
# or use environment variable
NO_COLOR=1 task build

Task Information

--status

Check if tasks are up-to-date without running them.

task build --status

--summary

Show detailed information about a task.

task build --summary

--json

Output task information in JSON format (use with --list or --list-all).

task --list --json

--sort <mode>

Change task listing order. Available modes: default, alphanumeric, none.

task --list --sort alphanumeric

Watch Mode

-w, --watch

Watch for file changes and re-run tasks automatically.

task build --watch

-I, --interval <duration>

Set watch interval (default: 5s). Must be a valid Go duration.

task build --watch --interval 1s

Interactive

-y, --yes

Automatically answer "yes" to all prompts.

task deploy --yes

Exit Codes

Task uses specific exit codes to indicate different types of errors:

Success

• 0 - Success

General Errors (1-99)

• 1 - Unknown error occurred

Taskfile Errors (100-199)

• 100 - No Taskfile found
• 101 - Taskfile already exists (when using --init)
• 102 - Invalid or unparseable Taskfile
• 103 - Remote Taskfile download failed
• 104 - Remote Taskfile not trusted
• 105 - Remote Taskfile fetch not secure
• 106 - No cache for remote Taskfile in offline mode
• 107 - No schema version defined in Taskfile

Task Errors (200-255)

• 200 - Task not found
• 201 - Command execution error
• 202 - Attempted to run internal task
• 203 - Multiple tasks with same name/alias
• 204 - Task called too many times (recursion limit)
• 205 - Task cancelled by user
• 206 - Missing required variables
• 207 - Variable has incorrect value

::: info

When using -x/--exit-code, failed command exit codes are passed through instead of the above codes.

:::

::: tip

The complete list of exit codes is available in the repository at errors/errors.go.

:::

JSON Output Format

When using --json with --list or --list-all:

{
  "tasks": [
    {
      "name": "build",
      "task": "build",
      "desc": "Build the application",
      "summary": "Compiles the source code and generates binaries",
      "up_to_date": false,
      "location": {
        "line": 12,
        "column": 3,
        "taskfile": "/path/to/Taskfile.yml"
      }
    }
  ],
  "location": "/path/to/Taskfile.yml"
}