Configuration 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
• Environment variables
• Command-line flags

In this document, we will look at the first of the three options, configuration files.

File Precedence

Task will automatically look for directories containing configuration files in the following order with the highest priority first:

• Current directory (or the one specified by the --taskfile/--entrypoint flags).
• Each directory walking up the file tree from the current directory (or the one specified by the --taskfile/--entrypoint flags) until we reach the user's home directory or the root directory of that drive.
• The users $HOME directory.
• The $XDG_CONFIG_HOME/task directory.

Config files in the current directory, its parent folders or home directory should be called .taskrc.yml or .taskrc.yaml. Config files in the $XDG_CONFIG_HOME/task directory are named the same way, but should not contain the . prefix.

All config files will be merged together into a unified config, starting with the lowest priority file in $XDG_CONFIG_HOME/task with each subsequent file overwriting the previous one if values are set.

For example, given the following files:

$XDG_CONFIG_HOME/task/taskrc.yml

# lowest priority global config
option_1: foo
option_2: foo
option_3: foo

$HOME/.taskrc.yml

option_1: bar
option_2: bar

$HOME/path/to/project/.taskrc.yml

# highest priority project config
option_1: baz

You would end up with the following configuration:

option_1: baz # Taken from $HOME/path/to/project/.taskrc.yml
option_2: bar # Taken from $HOME/.taskrc.yml
option_3: foo # Taken from $XDG_CONFIG_HOME/task/.taskrc.yml

Configuration Options

experiments

The experiments section allows you to enable Task's experimental features. These options are not enumerated here. Instead, please refer to our experiments documentation for more information.

experiments:
  feature_name: 1
  another_feature: 2

verbose

• Type: boolean
• Default: false
• Description: Enable verbose output for all tasks
• CLI equivalent: -v, --verbose
• Environment variable: TASK_VERBOSE

verbose: true

silent

• Type: boolean
• Default: false
• Description: Disables echoing of commands
• CLI equivalent: -s, --silent
• Environment variable: TASK_SILENT

silent: true

color

• Type: boolean
• Default: true
• Description: Enable colored output. Colors are automatically enabled in CI environments (CI=true).
• CLI equivalent: -c, --color
• Environment variable: TASK_COLOR

color: false

disable-fuzzy

• Type: boolean
• Default: false
• Description: Disable fuzzy matching for task names. When enabled, Task will not suggest similar task names when you mistype a task name.
• CLI equivalent: --disable-fuzzy
• Environment variable: TASK_DISABLE_FUZZY

disable-fuzzy: true

concurrency

• Type: integer
• Minimum: 1
• Description: Number of concurrent tasks to run
• CLI equivalent: -C, --concurrency
• Environment variable: TASK_CONCURRENCY

concurrency: 4

failfast

• Type: boolean
• Default: false
• Description: Stop executing dependencies as soon as one of them fail
• CLI equivalent: -F, --failfast
• Environment variable: TASK_FAILFAST

failfast: true

interactive

• Type: boolean
• Default: false
• Description: Prompt for missing required variables instead of failing. When enabled, Task will display an interactive prompt for any missing required variable. Requires a TTY. Task automatically detects non-TTY environments (CI pipelines, etc.) and skips prompts.
• CLI equivalent: --interactive

interactive: true

temp-dir

• Type: string
• Default: ./.task
• Description: Directory to store Task temporary files, such as checksums and temporary metadata. Relative paths are relative to the root Taskfile.
• Environment variable: TASK_TEMP_DIR

temp-dir: .task

remote

• Type: object
• Description: Remote configuration settings for handling remote Taskfiles.

remote.insecure

• Type: boolean
• Default: false
• Description: Allow insecure connections when fetching remote Taskfiles
• CLI equivalent: --insecure
• Environment variable: TASK_REMOTE_INSECURE

remote:
  insecure: true

remote.offline

• Type: boolean
• Default: false
• Description: Work in offline mode, preventing remote Taskfile fetching
• CLI equivalent: --offline
• Environment variable: TASK_REMOTE_OFFLINE

remote:
  offline: true

remote.timeout

• Type: string
• Default: 10s
• Pattern: ^[0-9]+(ns|us|µs|ms|s|m|h)$
• Description: Timeout duration for remote operations (e.g., '30s', '5m')
• CLI equivalent: --timeout
• Environment variable: TASK_REMOTE_TIMEOUT

remote:
  timeout: '1m'

remote.cache-expiry

• Type: string
• Default: 0s (no cache)
• Pattern: ^[0-9]+(ns|us|µs|ms|s|m|h)$
• Description: Cache expiry duration for remote Taskfiles (e.g., '1h', '24h')
• CLI equivalent: --expiry
• Environment variable: TASK_REMOTE_CACHE_EXPIRY

remote:
  cache-expiry: '6h'

remote.cache-dir

• Type: string
• Default: .task
• Description: Directory where remote Taskfiles are cached. Can be an absolute path (e.g., /var/cache/task) or relative to the Taskfile directory.
• CLI equivalent: --remote-cache-dir
• Environment variable: TASK_REMOTE_CACHE_DIR

remote:
  cache-dir: ~/.task

remote.trusted-hosts

• Type: array of strings
• Default: [] (empty list)
• Description: List of trusted hosts for remote Taskfiles. Hosts in this list will not prompt for confirmation when downloading Taskfiles
• CLI equivalent: --trusted-hosts
• Environment variable: TASK_REMOTE_TRUSTED_HOSTS (comma-separated)

remote:
  trusted-hosts:
    - github.com
    - gitlab.com
    - raw.githubusercontent.com
    - example.com:8080

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.

You can also specify trusted hosts via the command line:

# Trust specific host for this execution
task --trusted-hosts github.com -t https://github.com/user/repo.git//Taskfile.yml

# Trust multiple hosts (comma-separated)
task --trusted-hosts github.com,gitlab.com -t https://github.com/user/repo.git//Taskfile.yml

# Trust a host with a specific port
task --trusted-hosts example.com:8080 -t https://example.com:8080/Taskfile.yml

remote.headers

• Type: array of objects
• Default: [] (empty list)
• Description: HTTP headers to send when downloading a remote Taskfile from a given host, including authentication and custom headers

remote:
  headers:
    - host: gitlab.com
      headers:
        PRIVATE-TOKEN: '{{env "GITLAB_TOKEN"}}'
    - host: artifacts.example.com:8443
      headers:
        Authorization: 'Bearer {{env "ARTIFACTS_TOKEN"}}'
        Accept: application/yaml
        X-Custom-Header: custom-value

Use this option for authentication, content negotiation or other headers your server expects. For authentication, this is the recommended way to access a remote Taskfile. Unlike a credential placed in the URL, the header never appears in your Taskfile, in the confirmation prompt or in an error message, so the include URL stays safe to commit.

Each entry applies to a single host, matched exactly and including the port if the URL has one — the same rule as remote.trusted-hosts. Header values may reference templating functions, evaluated when Task contacts the host. Values starting with {{ must be quoted, as YAML would otherwise read them as a mapping. An undefined environment variable expands to nothing, so the header is sent empty. For an authentication header, this may cause the server to reject the request with a 401.

Functions compose, so an Authorization header needs no manual encoding:

remote:
  headers:
    - host: artifacts.example.com
      headers:
        Authorization: 'Basic {{ printf "%s:%s" (env "USER") (env "PASS") | b64enc }}'

WARNING

Only functions are available here — {{.GITLAB_TOKEN}} and other variable references resolve to nothing. The configuration file is read before any Taskfile, so no variable exists yet. Use {{env "GITLAB_TOKEN"}} instead.

The header your server expects depends on the service:

Service	Header
GitLab API	PRIVATE-TOKEN (or JOB-TOKEN in CI)
GitHub API	Authorization: Bearer <token>
Artifactory	X-JFrog-Art-Api

There is no CLI flag or environment variable for this option: a token given on the command line would be visible to any process listing it.

WARNING

Headers are only sent to the host they are configured for. If that host answers with a redirect to another one, the request follows the redirect without them, and will likely fail — point the URL at the final host instead. Headers are also HTTP-only: a Taskfile fetched over git should authenticate with SSH or a git credential helper.

remote.cacert

• Type: string
• Default: ""
• Description: Path to a custom CA certificate file for TLS verification

remote:
  cacert: '/path/to/ca.crt'

remote.cert

• Type: string
• Default: ""
• Description: Path to a client certificate file for mTLS authentication

remote:
  cert: '/path/to/client.crt'

remote.cert-key

• Type: string
• Default: ""
• Description: Path to the client certificate private key file

remote:
  cert-key: '/path/to/client.key'

Example Configuration

Here's a complete example of a .taskrc.yml file with all available options:

# Global settings
verbose: true
silent: false
color: true
disable-fuzzy: false
concurrency: 2
temp-dir: .task
remote:
  insecure: false
  offline: false
  timeout: '30s'
  cache-expiry: '24h'
  cache-dir: ~/.task
  trusted-hosts:
    - github.com
    - gitlab.com
  headers:
    - host: gitlab.com
      headers:
        PRIVATE-TOKEN: '{{env "GITLAB_TOKEN"}}'
  cacert: ''
  cert: ''
  cert-key: ''

# Enable experimental features
experiments:
  GENTLE_FORCE: 1