---
url: /docs/reference/cli.md
description: Complete reference for Task CLI commands, flags, and exit codes
---

# 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:

* [Configuration files](/docs/reference/config.md)
* [Environment variables](/docs/reference/environment.md)
* *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:

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

* **Config equivalent**: [`verbose`](/docs/reference/config.md#verbose)
* **Environment variable**: [`TASK_VERBOSE`](/docs/reference/environment.md#task-verbose)

```bash
task build --verbose
```

#### `-s, --silent`

Disable command echoing.

* **Config equivalent**: [`silent`](/docs/reference/config.md#silent)
* **Environment variable**: [`TASK_SILENT`](/docs/reference/environment.md#task-silent)

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

* **Config equivalent**: [`disable-fuzzy`](/docs/reference/config.md#disable-fuzzy)
* **Environment variable**:
  [`TASK_DISABLE_FUZZY`](/docs/reference/environment.md#task-disable-fuzzy)

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

* **Config equivalent**: [`failfast`](/docs/reference/config.md#failfast)
* **Environment variable**: [`TASK_FAILFAST`](/docs/reference/environment.md#task-failfast)

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

* **Environment variable**: [`TASK_DRY`](/docs/reference/environment.md#task-dry)

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

* **Config equivalent**: [`concurrency`](/docs/reference/config.md#concurrency)
* **Environment variable**:
  [`TASK_CONCURRENCY`](/docs/reference/environment.md#task-concurrency)

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

* **Config equivalent**: [`temp-dir`](/docs/reference/config.md#temp-dir)
* **Environment variable**: [`TASK_TEMP_DIR`](/docs/reference/environment.md#task-temp-dir)

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

### Output Control

#### `-o, --output <mode>`

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

* **Environment variable**: [`TASK_OUTPUT`](/docs/reference/environment.md#task-output)

```bash
task test --output group
```

#### `--output-group-begin <template>`

Message template to print before grouped output.

* **Environment variable**:
  [`TASK_OUTPUT_GROUP_BEGIN`](/docs/reference/environment.md#task-output-group-begin)

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

#### `--output-group-end <template>`

Message template to print after grouped output.

* **Environment variable**:
  [`TASK_OUTPUT_GROUP_END`](/docs/reference/environment.md#task-output-group-end)

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

#### `--output-group-error-only`

Only show command output on non-zero exit codes.

* **Environment variable**:
  [`TASK_OUTPUT_GROUP_ERROR_ONLY`](/docs/reference/environment.md#task-output-group-error-only)

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

#### `-c, --color`

Control colored output. Enabled by default.

* **Config equivalent**: [`color`](/docs/reference/config.md#color)
* **Environment variable**: [`TASK_COLOR`](/docs/reference/environment.md#task-color)

```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](https://pkg.go.dev/time#ParseDuration).

```bash
task build --watch --interval 1s
```

### Interactive

#### `-y, --yes`

Automatically answer "yes" to all prompts.

* **Environment variable**:
  [`TASK_ASSUME_YES`](/docs/reference/environment.md#task-assume-yes)

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

* **Environment variable**:
  [`TASK_INTERACTIVE`](/docs/reference/environment.md#task-interactive)

```bash
task deploy --interactive
```

### Remote

The following flags are used to control the behavior of
[remote Taskfiles](/docs/remote-taskfiles.md).

#### `--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`](https://github.com/go-task/task/blob/main/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"
}
```