Task

Appearance

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:

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:

bash
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.

bash
task build
task test lint
task deploy --force

task --list ​

List all available tasks with their descriptions.

bash
task --list
task -l

task --list-all ​

List all tasks, including those without descriptions.

bash
task --list-all
task -a

task --init ​

Create a new Taskfile.yml in the current directory.

bash
task --init
task -i

TIP

Combine --list or --list-all with --silent (-ls or -as for shortants) to list only the task names in each line. Useful for scripting with grep or similar.

Options ​

General ​

-h, --help ​

Show help information.

bash
task --help

--version ​

Show Task version.

bash
task --version

-v, --verbose ​

Enable verbose mode for detailed output.

bash
task build --verbose

-s, --silent ​

Disable command echoing.

bash
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.

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

Execution Control ​

-F, --failfast ​

Stop executing dependencies as soon as one of them fails.

bash
task build --failfast

-f, --force ​

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

bash
task build --force

-n, --dry ​

Compile and print tasks without executing them.

bash
task deploy --dry

-p, --parallel ​

Execute multiple tasks in parallel.

bash
task test lint --parallel

-C, --concurrency <number> ​

Limit the number of concurrent tasks. Zero means unlimited.

bash
task test --concurrency 4

-x, --exit-code ​

Pass through the exit code of failed commands.

bash
task test --exit-code

File and Directory ​

-d, --dir <path> ​

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

bash
task build --dir ./backend

-t, --taskfile <file> ​

Specify a custom Taskfile path.

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

-g, --global ​

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

bash
task backup --global

--temp-dir <path> ​

Set the directory used to store Task temporary files, such as checksums. Relative paths are relative to the root Taskfile.

bash
task build --temp-dir .task-cache

Output Control ​

-o, --output <mode> ​

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

bash
task test --output group

--output-group-begin <template> ​

Message template to print before grouped output.

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

--output-group-end <template> ​

Message template to print after grouped output.

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

--output-group-error-only ​

Only show command output on non-zero exit codes.

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

-c, --color ​

Control colored output. Enabled by default.

bash
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.

bash
task build --status

--summary ​

Show detailed information about a task.

bash
task build --summary

--json ​

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

bash
task --list --json

--sort <mode> ​

Change task listing order. Available modes:

  • default - Sorts tasks alphabetically by name, but ensures that root tasks (tasks without a namespace) are listed before namespaced tasks.
  • alphanumeric - Sort tasks alphabetically by name.
  • none - No sorting. Uses the order as defined in the Taskfile.
bash
task --list --sort alphanumeric

Watch Mode ​

-w, --watch ​

Watch for file changes and re-run tasks automatically.

bash
task build --watch

-I, --interval <duration> ​

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

bash
task build --watch --interval 1s

Interactive ​

-y, --yes ​

Automatically answer "yes" to all prompts.

bash
task deploy --yes

--interactive ​

Enable interactive prompts for missing required variables. When a required variable is not provided, Task will prompt for input instead of failing.

Task automatically detects non-TTY environments (like CI pipelines) and skips prompts. This flag can also be set in .taskrc.yml to enable prompts by default.

bash
task deploy --interactive

Remote ​

The following flags are used to control the behavior of remote Taskfiles.

--insecure ​

Allow insecure connections when fetching remote Taskfiles.

--offline ​

Work in offline mode, preventing remote Taskfile fetching.

--download ​

Forces task to download remote Taskfiles and ignore any cached versions.

--timeout ​

Timeout duration for remote operations (e.g., '30s', '5m').

--clear-cache ​

Wipe the cache of remote Taskfiles and checksums.

--expiry ​

Cache expiry duration for remote Taskfiles (e.g., '1h', '24h').

--remote-cache-dir ​

Directory where remote Taskfiles are cached. Can be an absolute path (e.g., /var/cache/task) or relative to the Taskfile directory.

--trusted-hosts ​

List of (comma-separated) trusted hosts for remote Taskfiles. Hosts in this list will not prompt for confirmation when downloading Taskfiles.

Hosts in the trusted hosts list will automatically be trusted without prompting for confirmation when they are first downloaded or when their checksums change. The host matching includes the port if specified in the URL. Use with caution and only add hosts you fully trust.

--cacert ​

Path to a custom CA certificate file for TLS verification.

--cert ​

Path to a client certificate file for mTLS authentication.

--cert-key ​

Path to the client certificate private key file.

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
  • 108 - Remote Taskfile network timeout
  • 109 - Invalid Taskfile
  • 110 - Taskfile cycle detected
  • 111 - Taskfile does not match checksum

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
  • 208 - Task timed out

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:

json
{
  "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"
}