--- url: /docs/installation.md description: Installation methods for Task --- # Installation Task offers many installation methods. Check out the available methods below. ## Official Package Managers These installation methods are maintained by the Task team and are always up-to-date. :::info Package Repository Hosting [![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith\&style=for-the-badge)](https://cloudsmith.com) Package repository hosting for deb/rpm/apk is graciously provided by [Cloudsmith](https://cloudsmith.com). Cloudsmith is the only fully hosted, cloud-native, universal package management solution, that enables your organization to create, store and share packages in any format, to any place, with total confidence. ::: ### [dnf](https://docs.fedoraproject.org/en-US/quick-docs/dnf) ![Fedora](https://img.shields.io/badge/Fedora-51A2DA?logo=fedora\&logoColor=fff) ![CentOS](https://img.shields.io/badge/CentOS-002260?logo=centos\&logoColor=F0F0F0) ![Fedora](https://img.shields.io/badge/Red_Hat-EE0000?logo=redhat\&logoColor=white) {#dnf} \[[package](https://cloudsmith.io/~task/repos/task/packages/?sort=-format\&q=format%3Arpm)] If you Set up the repository by running : ```shell curl -1sLf 'https://dl.cloudsmith.io/public/task/task/setup.rpm.sh' | sudo -E bash ``` Then you can install Task with: ```shell dnf install task ``` ### [apt](https://doc.ubuntu-fr.org/apt) ![Ubuntu](https://img.shields.io/badge/Ubuntu-E95420?logo=Ubuntu\&logoColor=white) ![Debian](https://img.shields.io/badge/debian-red?logo=debian\&logoColor=orange\&color=darkred) ![Linux Mint](https://img.shields.io/badge/Linux%20Mint-87CF3E?logo=linuxmint\&logoColor=fff) {#apt} \[[package](https://cloudsmith.io/~task/repos/task/packages/?sort=-format\&q=format%3Adeb)] If you Set up the repository by running: ```shell curl -1sLf 'https://dl.cloudsmith.io/public/task/task/setup.deb.sh' | sudo -E bash ``` Then you can install Task with: ```shell apt install task ``` ### [apk](https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper) ![Alpine Linux](https://img.shields.io/badge/Alpine_Linux-0D597F?logo=alpinelinux\&logoColor=fff) {#apk} \[[package](https://cloudsmith.io/~task/repos/task/packages/?sort=-format\&q=format%3Aalpine)] Set up the repository by running: ```shell curl -1sLf 'https://dl.cloudsmith.io/public/task/task/setup.alpine.sh' | sudo -E bash ``` Then you can install Task with: ```shell apk add task ``` ### [Homebrew](https://brew.sh) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) {#homebrew} Task is available via our official Homebrew tap \[[source](https://github.com/go-task/homebrew-tap/blob/main/Formula/go-task.rb)]: ```shell brew install go-task/tap/go-task ``` Alternatively it can be installed from the official Homebrew repository \[[package](https://formulae.brew.sh/formula/go-task)] \[[source](https://github.com/Homebrew/homebrew-core/blob/master/Formula/g/go-task.rb)] by running: ```shell brew install go-task ``` ### [Snap](https://snapcraft.io/task) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) {#snap} Task is available on [Snapcraft](https://snapcraft.io/task) \[[source](https://github.com/go-task/snap/blob/main/snap/snapcraft.yaml)], but keep in mind that your Linux distribution should allow classic confinement for Snaps to Task work correctly: ```shell sudo snap install task --classic ``` ### [npm](https://www.npmjs.com) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#npm} Npm can be used as cross-platform way to install Task globally or as a dependency of your project \[[package](https://www.npmjs.com/package/@go-task/cli)] \[[source](https://github.com/go-task/task/blob/main/package.json)]: ```shell npm install -g @go-task/cli ``` ### [WinGet](https://github.com/microsoft/winget-cli) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#winget} Task is available via the [community repository](https://github.com/microsoft/winget-pkgs) \[[source](https://github.com/microsoft/winget-pkgs/tree/master/manifests/t/Task/Task)]: ```shell winget install Task.Task ``` ## Community-Maintained Package Managers ::: warning Community Maintained These installation methods are maintained by the community and may not always be up-to-date with the latest Task version. The Task team does not directly control these packages. ::: ### [Mise](https://mise.jdx.dev/) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#mise} Mise is a cross-platform package manager that acts as a "frontend" to a variety of other package managers "backends" such as `asdf`, `aqua` and `ubi`. If using Mise, we recommend using the `aqua` or `ubi` backends to install Task as these install directly from our GitHub releases. ::: code-group ```shell [aqua] mise use -g aqua:go-task/task@latest mise install ``` ```shell [ubi] mise use -g ubi:go-task/task mise install ``` ::: ### [Macports](https://macports.org) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) {#macports} Task repository is tracked by Macports \[[package](https://ports.macports.org/port/go-task/details/)] \[[source](https://github.com/macports/macports-ports/blob/master/devel/go-task/Portfile)]: ```shell port install go-task ``` ### [pip](https://pip.pypa.io) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#pip} Like npm, pip can be used as a cross-platform way to install Task \[[package](https://pypi.org/project/go-task-bin)] \[[source](https://github.com/Bing-su/pip-binary-factory/tree/main/task)]: ```shell pip install go-task-bin ``` ### [Chocolatey](https://chocolatey.org) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#chocolatey} \[[package](https://community.chocolatey.org/packages/go-task)] \[[source](https://github.com/Starz0r/ChocolateyPackagingScripts/blob/master/src/go-task_gh_build.py)] ```shell choco install go-task ``` ### [Scoop](https://scoop.sh) ![Windows](https://custom-icon-badges.demolab.com/badge/Windows-0078D6?logo=windows11\&logoColor=white) {#scoop} \[[source](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json)] ```shell scoop install task ``` ### Arch ([pacman](https://wiki.archlinux.org/title/Pacman)) ![Arch Linux](https://img.shields.io/badge/Arch%20Linux-1793D1?logo=arch-linux\&logoColor=fff) {#arch} \[[package](https://archlinux.org/packages/extra/x86_64/go-task/)] \[[source](https://gitlab.archlinux.org/archlinux/packaging/packages/go-task)] ```shell pacman -S go-task ``` ### Fedora ([dnf](https://docs.fedoraproject.org/en-US/quick-docs/dnf)) ![Fedora](https://img.shields.io/badge/Fedora-51A2DA?logo=fedora\&logoColor=fff) {#fedora-community} \[[package](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)] \[[source](https://src.fedoraproject.org/rpms/golang-github-task)] ```shell dnf install go-task ``` ### FreeBSD ([Ports](https://ports.freebsd.org/cgi/ports.cgi)) ![FreeBSD](https://img.shields.io/badge/FreeBSD-990000?logo=freebsd\&logoColor=fff) {#freebsd} \[[package](https://cgit.freebsd.org/ports/tree/devel/task)] \[[source](https://cgit.freebsd.org/ports/tree/devel/task/Makefile)] ```shell pkg install task ``` ### [Nix](https://nixos.org) ![Nix](https://img.shields.io/badge/Nix-5277C3?logo=nixos\&logoColor=fff) ![NixOS](https://img.shields.io/badge/NixOS-5277C3?logo=nixos\&logoColor=fff) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) {#nix} \[[source](https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/go/go-task/package.nix)] ```shell nix-env -iA nixpkgs.go-task ``` ### [pacstall](https://github.com/pacstall/pacstall) ![Debian](https://img.shields.io/badge/Debian-A81D33?logo=debian\&logoColor=fff) ![Ubuntu](https://img.shields.io/badge/Ubuntu-E95420?logo=ubuntu\&logoColor=fff) {#pacstall} \[[package](https://pacstall.dev/packages/go-task-deb)] \[[source](https://github.com/pacstall/pacstall-programs/blob/master/packages/go-task-deb/go-task-deb.pacscript)] ```shell pacstall -I go-task-deb ``` ### [pkgx](https://pkgx.sh) ![macOS](https://img.shields.io/badge/MacOS-000000?logo=apple\&logoColor=F0F0F0) ![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux\&logoColor=black) {#pkgx} \[[package](https://pkgx.dev/pkgs/taskfile.dev)] \[[source](https://github.com/pkgxdev/pantry/blob/main/projects/taskfile.dev/package.yml)] ```shell pkgx task ``` or, if you have pkgx integration enabled: ```shell task ``` ## Get The Binary ### Binary You can download the binary from the [releases page on GitHub](https://github.com/go-task/task/releases) and add to your `$PATH`. DEB, RPM and APK packages are also available. The `task_checksums.txt` file contains the SHA-256 checksum for each file. ### Install Script We also have an [install script](https://github.com/go-task/task/blob/main/install-task.sh) which is very useful in scenarios like CI. Many thanks to [GoDownloader](https://github.com/goreleaser/godownloader) for enabling the easy generation of this script. By default, it installs on the `./bin` directory relative to the working directory: ```shell sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d ``` It is possible to override the installation directory with the `-b` parameter. On Linux, common choices are `~/.local/bin` and `~/bin` to install for the current user or `/usr/local/bin` to install for all users: ```shell sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin ``` ::: warning On macOS and Windows, `~/.local/bin` and `~/bin` are not added to `$PATH` by default. ::: By default, it installs the latest version available. You can also specify a tag (available in [releases](https://github.com/go-task/task/releases)) to install a specific version: ```shell sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d v3.36.0 ``` Parameters are order specific, to set both installation directory and version: ```shell sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin v3.42.1 ``` ### GitHub Actions We have an [official GitHub Action](https://github.com/go-task/setup-task) to install Task in your GitHub workflows. This repository is forked from the fantastic project by the Arduino team. Check out the repository for more examples and configuration. ```yaml - name: Install Task uses: go-task/setup-task@v1 ``` ## Build From Source Ensure that you have a supported version of [Go](https://golang.org) properly installed and setup. You can find the minimum required version of Go in the [go.mod](https://github.com/go-task/task/blob/main/go.mod#L3) file. You can then install the latest release globally by running: ```shell go install github.com/go-task/task/v3/cmd/task@latest ``` Or you can install into another directory: ```shell env GOBIN=/bin go install github.com/go-task/task/v3/cmd/task@latest ``` ::: tip For CI environments we recommend using the [install script](#install-script) instead, which is faster and more stable, since it'll just download the latest released binary. ::: ## Go Tool If you're working in a Go project, a nice possibility is using `go tool`. `go tool` makes it easy to run Task without needing to install the binary manually. This works well on CI. To do that, just run the following to add Task as a tool in your Go project. Task will be added to your `go.mod`. ```bash go get -tool github.com/go-task/task/v3/cmd/task@latest ``` Then, prefix `go tool` when calling Task like below. Go will compile Task on demand before calling it. ```bash go tool task {arguments...} ``` ## Setup completions Some installation methods will automatically install completions too, but if this isn't working for you or your chosen method doesn't include them, you can run `task --completion ` to output a completion script for any supported shell. There are a couple of ways these completions can be added to your shell config: ### Option 1. Load the completions in your shell's startup config (Recommended) This method loads the completion script from the currently installed version of task every time you create a new shell. This ensures that your completions are always up-to-date. If your executable isn’t named task, set the `TASK_EXE` environment variable before running eval. ::: code-group ```shell [bash] # ~/.bashrc # export TASK_EXE='go-task' if needed eval "$(task --completion bash)" ``` ```shell [zsh] # ~/.zshrc # export TASK_EXE='go-task' if needed eval "$(task --completion zsh)" ``` ```shell [fish] # ~/.config/fish/config.fish # export TASK_EXE='go-task' if needed task --completion fish | source ``` ```powershell [powershell] # $PROFILE\Microsoft.PowerShell_profile.ps1 Invoke-Expression (&task --completion powershell | Out-String) ``` ::: ### Option 2. Copy the script to your shell's completions directory This method requires you to manually update the completions whenever Task is updated. However, it is useful if you want to modify the completions yourself. ::: code-group ```shell [bash] task --completion bash > /etc/bash_completion.d/task ``` ```shell [zsh] task --completion zsh > /usr/local/share/zsh/site-functions/_task ``` ```shell [fish] task --completion fish > ~/.config/fish/completions/task.fish ``` ::: ### Zsh customization The Zsh completion supports the standard `verbose` zstyle to control whether task descriptions are shown. By default, descriptions are displayed. To show only task names without descriptions, add this to your `~/.zshrc` (after the completion is loaded): ```shell zstyle ':completion:*:*:task:*' verbose false ``` By default, task aliases are also offered as completions. To complete only the canonical task names, add the `show-aliases` zstyle: ```shell zstyle ':completion:*:*:task:*' show-aliases false ``` --- --- url: /docs/getting-started.md description: Guide for getting started with Task --- # Getting Started The following guide will help introduce you to the basics of Task. We'll cover how to create a Taskfile, how to write a basic task and how to call it. If you haven't installed Task yet, head over to our [installation guide](installation). ## Creating your first Taskfile Once Task is installed, you can create your first Taskfile by running: ```shell task --init ``` This will create a file called `Taskfile.yml` in the current directory. If you want to create the file in another directory, you can pass an absolute or relative path to the directory into the command: ```shell task --init ./subdirectory ``` Or if you want the Taskfile to have a specific name, you can pass in the name of the file: ```shell task --init Custom.yml ``` This will create a Taskfile that looks something like this: ```yaml [Taskfile.yml] version: '3' vars: GREETING: Hello, World! tasks: default: desc: Print a greeting message cmds: - echo "{{.GREETING}}" silent: true ``` As you can see, all Taskfiles are written in [YAML format](https://yaml.org/). The `version` attribute specifies the minimum version of Task that can be used to run this file. The `vars` attribute is used to define variables that can be used in tasks. In this case, we are creating a string variable called `GREETING` with a value of `Hello, World!`. Finally, the `tasks` attribute is used to define the tasks that can be run. In this case, we have a task called `default` that echoes the value of the `GREETING` variable. The `silent` attribute is set to `true`, which means that the task metadata will not be printed when the task is run - only the output of the commands. ## Calling a task To call the task, invoke `task` followed by the name of the task you want to run. In this case, the name of the task is `default`, so you should run: ```shell task default ``` Note that we don't have to specify the name of the Taskfile. Task will automatically look for a file called `Taskfile.yml` (or any of Task's [supported file names](/docs/guide#supported-file-names)) in the current directory. Additionally, tasks with the name `default` are special. They can also be run without specifying the task name. If you created a Taskfile in a different directory, you can run it by passing the absolute or relative path to the directory as an argument using the `--dir` flag: ```shell task --dir ./subdirectory ``` Or if you created a Taskfile with a different name, you can run it by passing the name of the Taskfile as an argument using the `--taskfile` flag: ```shell task --taskfile Custom.yml ``` ## Adding a build task Let's create a task to build a program in Go. Start by adding a new task called `build` below the existing `default` task. We can then add a `cmds` attribute with a single command to build the program. Task uses [mvdan/sh](https://github.com/mvdan/sh), a native Go sh interpreter. So you can write sh/bash-like commands - even in environments where `sh` or `bash` are usually not available (like Windows). Just remember any executables called must be available as a built-in or in the system's `PATH`. When you're done, it should look something like this: ```yaml version: '3' vars: GREETING: Hello, World! tasks: default: desc: Print a greeting message cmds: - echo "{{.GREETING}}" silent: true build: cmds: - go build ./cmd/main.go ``` Call the task by running: ```shell task build ``` That's about it for the basics, but there's *so much* more that you can do with Task. Check out the rest of the documentation to learn more about all the features Task has to offer! We recommend taking a look at the [usage guide](/docs/guide) next. Alternatively, you can check out our reference docs for the [Taskfile schema](reference/schema) and [CLI](reference/cli). --- --- url: /docs/guide.md --- # Guide ## Running Taskfiles Specific Taskfiles can be called by specifying the `--taskfile` flag. If you don't specify a Taskfile, Task will automatically look for a file with one of the [supported file names](#supported-file-names) in the current directory. If you want to search in a different directory, you can use the `--dir` flag. ### Supported file names Task looks for files with the following 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` The `.dist` variants allow projects to have one committed file (`.dist`) while still allowing individual users to override the Taskfile by adding an additional `Taskfile.yml` (which would be in your `.gitignore`). ### Running a Taskfile from a subdirectory If a Taskfile cannot be found in the current working directory, it will walk up the file tree until it finds one (similar to how `git` works). When running Task from a subdirectory like this, it will behave as if you ran it from the directory containing the Taskfile. You can use this functionality along with the special `{{.USER_WORKING_DIR}}` variable to create some very useful reusable tasks. For example, if you have a monorepo with directories for each microservice, you can `cd` into a microservice directory and run a task command to bring it up without having to create multiple tasks or Taskfiles with identical content. For example: ```yaml version: '3' tasks: up: dir: '{{.USER_WORKING_DIR}}' preconditions: - test -f docker-compose.yml cmds: - docker-compose up -d ``` In this example, we can run `cd ` and `task up` and as long as the `` directory contains a `docker-compose.yml`, the Docker composition will be brought up. ### Running a global Taskfile If you call Task with the `--global` (alias `-g`) flag, it will look for your home directory instead of your working directory. In short, Task will look for a Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml}` . This is useful to have automation that you can run from anywhere in your system! ::: info When running your global Taskfile with `-g`, tasks will run on `$HOME` by default, and not on your working directory! As mentioned in the previous section, the `{{.USER_WORKING_DIR}}` special variable can be very handy here to run stuff on the directory you're calling `task -g` from. ```yaml version: '3' tasks: from-home: cmds: - pwd from-working-directory: dir: '{{.USER_WORKING_DIR}}' cmds: - pwd ``` ::: ### Reading a Taskfile from stdin Taskfile also supports reading from stdin. This is useful if you are generating Taskfiles dynamically and don't want write them to disk. To tell task to read from stdin, you must specify the `-t/--taskfile` flag with the special `-` value. You may then pipe into Task as you would any other program: ```shell task -t - < ./Taskfile.yml # OR cat ./Taskfile.yml | task -t - ``` ## Environment variables ### Task You can use `env` to set custom environment variables for a specific task: ```yaml version: '3' tasks: greet: cmds: - echo $GREETING env: GREETING: Hey, there! ``` Additionally, you can set global environment variables that will be available to all tasks: ```yaml version: '3' env: GREETING: Hey, there! tasks: greet: cmds: - echo $GREETING ``` ::: info `env` supports expansion and retrieving output from a shell command just like variables, as you can see in the [Variables](#variables) section. ::: ### .env files You can also ask Task to include `.env` like files by using the `dotenv:` setting: ::: code-group ```shell [.env] KEYNAME=VALUE ``` ```shell [testing/.env] ENDPOINT=testing.com ``` ::: ```yaml version: '3' env: ENV: testing dotenv: ['.env', '{{.ENV}}/.env', '{{.HOME}}/.env'] tasks: greet: cmds: - echo "Using $KEYNAME and endpoint $ENDPOINT" ``` When the same variable is defined in multiple dotenv files, the **first file in the list takes precedence**. This allows you to set up override patterns by placing higher-priority files first: ```yaml version: '3' dotenv: - .env.local # Highest priority - local developer overrides - .env.{{.ENV}} # Environment-specific settings - .env # Base defaults (lowest priority) ``` Dotenv files can also be specified at the task level: ```yaml version: '3' env: ENV: testing tasks: greet: dotenv: ['.env', '{{.ENV}}/.env', '{{.HOME}}/.env'] cmds: - echo "Using $KEYNAME and endpoint $ENDPOINT" ``` Environment variables specified explicitly at the task-level will override variables defined in dotfiles: ```yaml version: '3' env: ENV: testing tasks: greet: dotenv: ['.env', '{{.ENV}}/.env', '{{.HOME}}/.env'] env: KEYNAME: DIFFERENT_VALUE cmds: - echo "Using $KEYNAME and endpoint $ENDPOINT" ``` ::: info Please note that you are not currently able to use the `dotenv` key inside included Taskfiles. ::: ## Including other Taskfiles If you want to share tasks between different projects (Taskfiles), you can use the importing mechanism to include other Taskfiles using the `includes` keyword: ```yaml version: '3' includes: docs: ./documentation # will look for ./documentation/Taskfile.yml docker: ./DockerTasks.yml ``` The tasks described in the given Taskfiles will be available with the informed namespace. So, you'd call `task docs:serve` to run the `serve` task from `documentation/Taskfile.yml` or `task docker:build` to run the `build` task from the `DockerTasks.yml` file. Relative paths are resolved relative to the directory containing the including Taskfile. ### OS-specific Taskfiles You can include OS-specific Taskfiles by using a templating function: ```yaml version: '3' includes: build: ./Taskfile_{{OS}}.yml ``` ### Directory of included Taskfile By default, included Taskfile's tasks are run in the current directory, even if the Taskfile is in another directory, but you can force its tasks to run in another directory by using this alternative syntax: ```yaml version: '3' includes: docs: taskfile: ./docs/Taskfile.yml dir: ./docs ``` ::: info The included Taskfiles must be using the same schema version as the main Taskfile uses. ::: ### Optional includes Includes marked as optional will allow Task to continue execution as normal if the included file is missing. ```yaml version: '3' includes: tests: taskfile: ./tests/Taskfile.yml optional: true tasks: greet: cmds: - echo "This command can still be successfully executed if ./tests/Taskfile.yml does not exist" ``` ### Internal includes Includes marked as internal will set all the tasks of the included file to be internal as well (see the [Internal tasks](#internal-tasks) section below). This is useful when including utility tasks that are not intended to be used directly by the user. ```yaml version: '3' includes: tests: taskfile: ./taskfiles/Utils.yml internal: true ``` ### Flatten includes You can flatten the included Taskfile tasks into the main Taskfile by using the `flatten` option. It means that the included Taskfile tasks will be available without the namespace. ::: code-group ```yaml [Taskfile.yml] version: '3' includes: lib: taskfile: ./Included.yml flatten: true tasks: greet: cmds: - echo "Greet" - task: foo ``` ```yaml [Included.yml] version: '3' tasks: foo: cmds: - echo "Foo" ``` ::: If you run `task -a` it will print : ```sh task: Available tasks for this project: * greet: * foo ``` You can run `task foo` directly without the namespace. You can also reference the task in other tasks without the namespace. So if you run `task greet` it will run `greet` and `foo` tasks and the output will be : ```text Greet Foo ``` If multiple tasks have the same name, an error will be thrown: ::: code-group ```yaml [Taskfile.yml] version: '3' includes: lib: taskfile: ./Included.yml flatten: true tasks: greet: cmds: - echo "Greet" - task: foo ``` ```yaml [Included.yml] version: '3' tasks: greet: cmds: - echo "Foo" ``` ::: If you run `task -a` it will print: ```text task: Found multiple tasks (greet) included by "lib" ``` If the included Taskfile has a task with the same name as a task in the main Taskfile, you may want to exclude it from the flattened tasks. You can do this by using the [`excludes` option](#exclude-tasks-from-being-included). ### Exclude tasks from being included You can exclude tasks from being included by using the `excludes` option. This option takes the list of tasks to be excluded from this include. ::: code-group ```yaml [Taskfile.yml] version: '3' includes: included: taskfile: ./Included.yml excludes: [foo] ``` ```yaml [Included.yml] version: '3' tasks: foo: echo "Foo" bar: echo "Bar" ``` ::: `task included:foo` will throw an error because the `foo` task is excluded but `task included:bar` will work and display `Bar`. It's compatible with the `flatten` option. ### Vars of included Taskfiles You can also specify variables when including a Taskfile. This may be useful for having a reusable Taskfile that can be tweaked or even included more than once: ```yaml version: '3' includes: backend: taskfile: ./taskfiles/Docker.yml vars: DOCKER_IMAGE: backend_image frontend: taskfile: ./taskfiles/Docker.yml vars: DOCKER_IMAGE: frontend_image ``` ### Namespace aliases When including a Taskfile, you can give the namespace a list of `aliases`. This works in the same way as [task aliases](#task-aliases) and can be used together to create shorter and easier-to-type commands. ```yaml version: '3' includes: generate: taskfile: ./taskfiles/Generate.yml aliases: [gen] ``` ::: info Vars declared in the included Taskfile have preference over the variables in the including Taskfile! If you want a variable in an included Taskfile to be overridable, use the [default function](https://sprig.taskfile.dev/defaults.html): `MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`. ::: ## Internal tasks Internal tasks are tasks that cannot be called directly by the user. They will not appear in the output when running `task --list|--list-all`. Other tasks may call internal tasks in the usual way. This is useful for creating reusable, function-like tasks that have no useful purpose on the command line. ```yaml version: '3' tasks: build-image-1: cmds: - task: build-image vars: DOCKER_IMAGE: image-1 build-image: internal: true cmds: - docker build -t {{.DOCKER_IMAGE}} . ``` ## Task directory By default, tasks will be executed in the directory where the Taskfile is located. But you can easily make the task run in another folder, informing `dir`: ```yaml version: '3' tasks: serve: dir: public/www cmds: # run http server - caddy ``` If the directory does not exist, `task` creates it. ## Task dependencies > Dependencies run in parallel, so dependencies of a task should not depend one > another. If you want to force tasks to run serially, take a look at the > [Calling Another Task](#calling-another-task) section below. You may have tasks that depend on others. Just pointing them on `deps` will make them run automatically before running the parent task: ```yaml version: '3' tasks: build: deps: [assets] cmds: - go build -v -i main.go assets: cmds: - esbuild --bundle --minify css/index.css > public/bundle.css ``` In the above example, `assets` will always run right before `build` if you run `task build`. A task can have only dependencies and no commands to group tasks together: ```yaml version: '3' tasks: assets: deps: [js, css] js: cmds: - esbuild --bundle --minify js/index.js > public/bundle.js css: cmds: - esbuild --bundle --minify css/index.css > public/bundle.css ``` If there is more than one dependency, they always run in parallel for better performance. ::: tip You can also make the tasks given by the command line run in parallel by using the `--parallel` flag (alias `-p`). Example: `task --parallel js css`. ::: If you want to pass information to dependencies, you can do that the same manner as you would to [call another task](#calling-another-task): ```yaml version: '3' tasks: default: deps: - task: echo_sth vars: { TEXT: 'before 1' } - task: echo_sth vars: { TEXT: 'before 2' } silent: true cmds: - echo "after" echo_sth: cmds: - echo {{.TEXT}} ``` ### Fail-fast dependencies By default, Task waits for all dependencies to finish running before continuing. If you want Task to stop executing further dependencies as soon as one fails, you can set `failfast: true` on your [`.taskrc.yml`][config] or for a specific task: ```yaml # .taskrc.yml failfast: true # applies to all tasks ``` ```yaml # Taskfile.yml version: '3' tasks: default: deps: [task1, task2, task3] failfast: true # applies only to this task ``` Alternatively, you can use `--failfast`, which also work for `--parallel`. ## Platform specific tasks and commands If you want to restrict the running of tasks to explicit platforms, this can be achieved using the `platforms:` key. Tasks can be restricted to a specific OS, architecture or a combination of both. On a mismatch, the task or command will be skipped, and no error will be thrown. The values allowed as OS or Arch are valid `GOOS` and `GOARCH` values, as defined by the Go language [here](https://github.com/golang/go/blob/master/src/internal/syslist/syslist.go). The `build-windows` task below will run only on Windows, and on any architecture: ```yaml version: '3' tasks: build-windows: platforms: [windows] cmds: - echo 'Running command on Windows' ``` This can be restricted to a specific architecture as follows: ```yaml version: '3' tasks: build-windows-amd64: platforms: [windows/amd64] cmds: - echo 'Running command on Windows (amd64)' ``` It is also possible to restrict the task to specific architectures: ```yaml version: '3' tasks: build-amd64: platforms: [amd64] cmds: - echo 'Running command on amd64' ``` Multiple platforms can be specified as follows: ```yaml version: '3' tasks: build: platforms: [windows/amd64, darwin] cmds: - echo 'Running command on Windows (amd64) and macOS' ``` Individual commands can also be restricted to specific platforms: ```yaml version: '3' tasks: build: cmds: - cmd: echo 'Running command on Windows (amd64) and macOS' platforms: [windows/amd64, darwin] - cmd: echo 'Running on all platforms' ``` ## Calling another task When a task has many dependencies, they are executed concurrently. This will often result in a faster build pipeline. However, in some situations, you may need to call other tasks serially. In this case, use the following syntax: ```yaml version: '3' tasks: main-task: cmds: - task: task-to-be-called - task: another-task - echo "Both done" task-to-be-called: cmds: - echo "Task to be called" another-task: cmds: - echo "Another task" ``` Using the `vars` and `silent` attributes you can choose to pass variables and toggle [silent mode](#silent-mode) on a call-by-call basis: ```yaml version: '3' tasks: greet: vars: RECIPIENT: '{{default "World" .RECIPIENT}}' cmds: - echo "Hello, {{.RECIPIENT}}!" greet-pessimistically: cmds: - task: greet vars: { RECIPIENT: 'Cruel World' } silent: true ``` The above syntax is also supported in `deps`. ::: tip NOTE: If you want to call a task declared in the root Taskfile from within an [included Taskfile](#including-other-taskfiles), add a leading `:` like this: `task: :task-name`. ::: ## Prevent unnecessary work ### By fingerprinting locally generated files and their sources If a task generates something, you can inform Task the source and generated files, so Task will prevent running them if not necessary. ```yaml version: '3' tasks: build: deps: [js, css] cmds: - go build -v -i main.go js: cmds: - esbuild --bundle --minify js/index.js > public/bundle.js sources: - src/js/**/*.js generates: - public/bundle.js css: cmds: - esbuild --bundle --minify css/index.css > public/bundle.css sources: - src/css/**/*.css generates: - public/bundle.css ``` `sources` and `generates` can be files or glob patterns. When given, Task will compare the checksum of the source files to determine if it's necessary to run the task. If not, it will just print a message like `Task "js" is up to date`. `exclude:` can also be used to exclude files from fingerprinting. Sources are evaluated in order, so `exclude:` must come after the positive glob it is negating. ```yaml version: '3' tasks: css: sources: - mysources/**/*.css - exclude: mysources/ignoreme.css generates: - public/bundle.css ``` If you prefer these check to be made by the modification timestamp of the files, instead of its checksum (content), just set the `method` property to `timestamp`. This can be done at two levels: At the task level for a specific task: ```yaml version: '3' tasks: build: cmds: - go build . sources: - ./*.go generates: - app{{exeExt}} method: timestamp ``` At the root level of the Taskfile to apply it globally to all tasks: ```yaml version: '3' method: timestamp # Will be the default for all tasks tasks: build: cmds: - go build . sources: - ./*.go generates: - app{{exeExt}} ``` In situations where you need more flexibility the `status` keyword can be used. You can even combine the two. See the documentation for [status](#using-programmatic-checks-to-indicate-a-task-is-up-to-date) for an example. ::: info By default, task stores checksums on a local `.task` directory in the project's directory. Most of the time, you'll want to have this directory on `.gitignore` (or equivalent) so it isn't committed. (If you have a task for code generation that is committed it may make sense to commit the checksum of that task as well, though). If you want these files to be stored in another directory, you can set a `TASK_TEMP_DIR` environment variable in your machine. It can contain a relative path like `tmp/task` that will be interpreted as relative to the project directory, or an absolute or home path like `/tmp/.task` or `~/.task` (subdirectories will be created for each project). ```shell export TASK_TEMP_DIR='~/.task' ``` ::: ::: info Each task has only one checksum stored for its `sources`. If you want to distinguish a task by any of its input variables, you can add those variables as part of the task's label, and it will be considered a different task. This is useful if you want to run a task once for each distinct set of inputs until the sources actually change. For example, if the sources depend on the value of a variable, or you if you want the task to rerun if some arguments change even if the source has not. ::: ::: tip The method `none` skips any validation and always runs the task. ::: ::: info For the `checksum` (default) or `timestamp` method to work, it is only necessary to inform the source files. When the `timestamp` method is used, the last time of the running the task is considered as a generate. ::: ### Using programmatic checks to indicate a task is up to date Alternatively, you can inform a sequence of tests as `status`. If no error is returned (exit status 0), the task is considered up-to-date: ```yaml version: '3' tasks: generate-files: cmds: - mkdir directory - touch directory/file1.txt - touch directory/file2.txt # test existence of files status: - test -d directory - test -f directory/file1.txt - test -f directory/file2.txt ``` Normally, you would use `sources` in combination with `generates` - but for tasks that generate remote artifacts (Docker images, deploys, CD releases) the checksum source and timestamps require either access to the artifact or for an out-of-band refresh of the `.checksum` fingerprint file. Two special variables `{{.CHECKSUM}}` and `{{.TIMESTAMP}}` are available for interpolation within `cmds` and `status` commands, depending on the method assigned to fingerprint the sources. Only `source` globs are fingerprinted. Note that the `{{.TIMESTAMP}}` variable is a "live" Go `time.Time` struct, and can be formatted using any of the methods that `time.Time` responds to. See [the Go Time documentation](https://golang.org/pkg/time/) for more information. You can use `--force` or `-f` if you want to force a task to run even when up-to-date. Also, `task --status [tasks]...` will exit with a non-zero [exit code](/docs/reference/cli#exit-codes) if any of the tasks are not up-to-date. `status` can be combined with the [fingerprinting](#by-fingerprinting-locally-generated-files-and-their-sources) to have a task run if either the source/generated artifacts changes, or the programmatic check fails: ```yaml version: '3' tasks: build:prod: desc: Build for production usage. cmds: - composer install # Run this task if source files changes. sources: - composer.json - composer.lock generates: - ./vendor/composer/installed.json - ./vendor/autoload.php # But also run the task if the last build was not a production build. status: - grep -q '"dev"{{:}} false' ./vendor/composer/installed.json ``` ### Using programmatic checks to cancel the execution of a task and its dependencies In addition to `status` checks, `preconditions` checks are the logical inverse of `status` checks. That is, if you need a certain set of conditions to be *true* you can use the `preconditions` stanza. `preconditions` are similar to `status` lines, except they support `sh` expansion, and they SHOULD all return 0. ```yaml version: '3' tasks: generate-files: cmds: - mkdir directory - touch directory/file1.txt - touch directory/file2.txt # test existence of files preconditions: - test -f .env - sh: '[ 1 = 0 ]' msg: "One doesn't equal Zero, Halting" ``` Preconditions can set specific failure messages that can tell a user what steps to take using the `msg` field. If a task has a dependency on a sub-task with a precondition, and that precondition is not met - the calling task will fail. Note that a task executed with a failing precondition will not run unless `--force` is given. Unlike `status`, which will skip a task if it is up to date and continue executing tasks that depend on it, a `precondition` will fail a task, along with any other tasks that depend on it. ```yaml version: '3' tasks: task-will-fail: preconditions: - sh: 'exit 1' task-will-also-fail: deps: - task-will-fail task-will-still-fail: cmds: - task: task-will-fail - echo "I will not run" ``` ### Conditional execution with `if` The `if` attribute allows you to conditionally skip tasks or commands based on a shell command's exit code. Unlike `preconditions` which fail and stop execution, `if` simply skips the task or command when the condition is not met and continues with the rest of the Taskfile. #### Task-level `if` When `if` is set on a task, the entire task is skipped if the condition fails: ```yaml version: '3' tasks: deploy: if: '[ "$CI" = "true" ]' cmds: - echo "Deploying..." - ./deploy.sh ``` #### Command-level `if` When `if` is set on a command, only that specific command is skipped: ```yaml version: '3' tasks: build: cmds: - cmd: echo "Building for production" if: '[ "$ENV" = "production" ]' - cmd: echo "Building for development" if: '[ "$ENV" = "development" ]' - go build ./... ``` #### Using templates in `if` conditions You can use Go template expressions in `if` conditions. Template expressions like `{{eq .VAR "value"}}` evaluate to `true` or `false`, which are valid shell commands (`true` exits with 0, `false` exits with 1): ```yaml version: '3' tasks: conditional: vars: ENABLE_FEATURE: "true" cmds: - cmd: echo "Feature is enabled" if: '{{eq .ENABLE_FEATURE "true"}}' - cmd: echo "Feature is disabled" if: '{{ne .ENABLE_FEATURE "true"}}' ``` #### Using `if` with `for` loops When used inside a `for` loop, the `if` condition is evaluated for each iteration: ```yaml version: '3' tasks: process-items: cmds: - for: ['a', 'b', 'c'] cmd: echo "processing {{.ITEM}}" if: '[ "{{.ITEM}}" != "b" ]' ``` This will output: ``` processing a processing c ``` #### `if` vs `preconditions` | Aspect | `if` | `preconditions` | |--------|------|-----------------| | On failure | Skips (continues) | Fails (stops) | | Message | Only in verbose mode | Always shown | | Use case | "Run if possible" | "Must be true" | Use `if` when you want optional conditional execution that shouldn't stop the workflow. Use `preconditions` when the condition must be met for the task to make sense. ### Limiting when tasks run If a task executed by multiple `cmds` or multiple `deps` you can control when it is executed using `run`. `run` can also be set at the root of the Taskfile to change the behavior of all the tasks unless explicitly overridden. Supported values for `run`: * `always` (default) always attempt to invoke the task regardless of the number of previous executions * `once` only invoke this task once regardless of the number of references * `when_changed` only invokes the task once for each unique set of variables passed into the task ```yaml version: '3' tasks: default: cmds: - task: generate-file vars: { CONTENT: '1' } - task: generate-file vars: { CONTENT: '2' } - task: generate-file vars: { CONTENT: '2' } generate-file: run: when_changed deps: - install-deps cmds: - echo {{.CONTENT}} install-deps: run: once cmds: - sleep 5 # long operation like installing packages ``` ### Ensuring required variables are set If you want to check that certain variables are set before running a task then you can use `requires`. This is useful when might not be clear to users which variables are needed, or if you want clear message about what is required. Also some tasks could have dangerous side effects if run with un-set variables. Using `requires` you specify an array of strings in the `vars` sub-section under `requires`, these strings are variable names which are checked prior to running the task. If any variables are un-set then the task will error and not run. Environmental variables are also checked. Syntax: ```yaml requires: vars: [] # Array of strings ``` ::: info Variables set to empty zero length strings, will pass the `requires` check. ::: Example of using `requires`: ```yaml version: '3' tasks: docker-build: cmds: - 'docker build . -t {{.IMAGE_NAME}}:{{.IMAGE_TAG}}' # Make sure these variables are set before running requires: vars: [IMAGE_NAME, IMAGE_TAG] ``` ### Ensuring required variables have allowed values If you want to ensure that a variable is set to one of a predefined set of valid values before executing a task, you can use requires. This is particularly useful when there are strict requirements for what values a variable can take, and you want to provide clear feedback to the user when an invalid value is detected. To use `requires`, you specify an array of allowed values in the vars sub-section under requires. Task will check if the variable is set to one of the allowed values. If the variable does not match any of these values, the task will raise an error and stop execution. This check applies both to user-defined variables and environment variables. Example of using `requires`: ```yaml version: '3' tasks: deploy: cmds: - echo "deploying to {{.ENV}}" requires: vars: - name: ENV enum: [dev, beta, prod] ``` If `ENV` is not one of 'dev', 'beta' or 'prod' an error will be raised. ::: info This is supported only for string variables. ::: ### Using variable references for enum values Instead of hardcoding enum values, you can reference a variable containing the allowed values. This is useful when you want to define allowed values once and reuse them, or when the values are computed dynamically. Use the `ref` key to reference a variable: ```yaml version: '3' vars: ALLOWED_ENVS: [dev, staging, prod] tasks: deploy: requires: vars: - name: ENV enum: ref: .ALLOWED_ENVS cmds: - echo "Deploying to {{.ENV}}" ``` You can also use template expressions to transform the value: ```yaml version: '3' vars: CONFIG: sh: cat config.json tasks: deploy: requires: vars: - name: ENV enum: ref: ( .CONFIG | fromJson ).allowed_environments cmds: - echo "Deploying to {{.ENV}}" ``` Or generate values dynamically from a shell command: ```yaml version: '3' vars: AVAILABLE_SERVICES: sh: ls services/ tasks: deploy: requires: vars: - name: SERVICE enum: ref: .AVAILABLE_SERVICES | splitLines | compact cmds: - echo "Deploying {{.SERVICE}}" ``` ### Prompting for missing variables interactively If you want Task to prompt users for missing required variables instead of failing, you can enable interactive mode in your `.taskrc.yml`: ```yaml # ~/.taskrc.yml interactive: true ``` When enabled, Task will display an interactive prompt for any missing required variable. For variables with an `enum`, a selection menu is shown. For variables without an enum, a text input is displayed. ```yaml # Taskfile.yml version: '3' tasks: deploy: requires: vars: - name: ENVIRONMENT enum: [dev, staging, prod] - VERSION cmds: - echo "Deploying {{.VERSION}} to {{.ENVIRONMENT}}" ``` ```shell $ task deploy ? Select value for ENVIRONMENT: ❯ dev staging prod ? Enter value for VERSION: 1.0.0 Deploying 1.0.0 to prod ``` If the variable is already set (via CLI, environment, or Taskfile), no prompt is shown: ```shell $ task deploy ENVIRONMENT=prod VERSION=1.0.0 Deploying 1.0.0 to prod ``` ::: info Interactive prompts require a TTY (terminal). Task automatically detects non-interactive environments like GitHub Actions, GitLab CI, and other CI pipelines where stdin/stdout are not connected to a terminal. In these cases, prompts are skipped and missing variables will cause an error as usual. You can enable prompts from the command line with `--interactive` or by setting `interactive: true` in your `.taskrc.yml`. ::: ## Variables Task allows you to set variables using the `vars` keyword. The following variable types are supported: * `string` * `bool` * `int` * `float` * `array` * `map` ::: info Defining a map requires that you use a special `map` subkey (see example below). ::: ```yaml version: 3 tasks: foo: vars: STRING: 'Hello, World!' BOOL: true INT: 42 FLOAT: 3.14 ARRAY: [1, 2, 3] MAP: map: { A: 1, B: 2, C: 3 } cmds: - 'echo {{.STRING}}' # Hello, World! - 'echo {{.BOOL}}' # true - 'echo {{.INT}}' # 42 - 'echo {{.FLOAT}}' # 3.14 - 'echo {{.ARRAY}}' # [1 2 3] - 'echo {{index .ARRAY 0}}' # 1 - 'echo {{.MAP}}' # map[A:1 B:2 C:3] - 'echo {{.MAP.A}}' # 1 ``` Variables can be set in many places in a Taskfile. When executing [templates][templating-reference], Task will look for variables in the order listed below (most important first): * Variables declared in the task definition * Variables given while calling a task from another (See [Calling another task](#calling-another-task) above) * Variables of the [included Taskfile](#including-other-taskfiles) (when the task is included) * Variables of the [inclusion of the Taskfile](#vars-of-included-taskfiles) (when the task is included) * Global variables (those declared in the `vars:` option in the Taskfile) * Environment variables Example of sending parameters with environment variables: ```shell $ TASK_VARIABLE=a-value task do-something ``` ::: tip A special variable `.TASK` is always available containing the task name. ::: Since some shells do not support the above syntax to set environment variables (Windows) tasks also accept a similar style when not at the beginning of the command. ```shell $ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!" ``` Example of locally declared vars: ```yaml version: '3' tasks: print-var: cmds: - echo "{{.VAR}}" vars: VAR: Hello! ``` Example of global vars in a `Taskfile.yml`: ```yaml version: '3' vars: GREETING: Hello from Taskfile! tasks: greet: cmds: - echo "{{.GREETING}}" ``` Example of a `default` value to be overridden from CLI: ```yaml version: '3' tasks: greet_user: desc: 'Greet the user with a name.' vars: USER_NAME: '{{.USER_NAME| default "DefaultUser"}}' cmds: - echo "Hello, {{.USER_NAME}}!" ``` ```shell $ task greet_user task: [greet_user] echo "Hello, DefaultUser!" Hello, DefaultUser! $ task greet_user USER_NAME="Bob" task: [greet_user] echo "Hello, Bob!" Hello, Bob! ``` ### Dynamic variables The below syntax (`sh:` prop in a variable) is considered a dynamic variable. The value will be treated as a command and the output assigned. If there are one or more trailing newlines, the last newline will be trimmed. ```yaml version: '3' tasks: build: cmds: - go build -ldflags="-X main.Version={{.GIT_COMMIT}}" main.go vars: GIT_COMMIT: sh: git log -n 1 --format=%h ``` This works for all types of variables. ### Referencing other variables Templating is great for referencing string values if you want to pass a value from one task to another. However, the templating engine is only able to output strings. If you want to pass something other than a string to another task then you will need to use a reference (`ref`) instead. ::: code-group ```yaml [Templating Engine] version: 3 tasks: foo: vars: FOO: [A, B, C] # <-- FOO is defined as an array cmds: - task: bar vars: FOO: '{{.FOO}}' # <-- FOO gets converted to a string when passed to bar bar: cmds: - 'echo {{index .FOO 0}}' # <-- FOO is a string so the task outputs '91' which is the ASCII code for '[' instead of the expected 'A' ``` ```yaml [Reference] version: 3 tasks: foo: vars: FOO: [A, B, C] # <-- FOO is defined as an array cmds: - task: bar vars: FOO: ref: .FOO # <-- FOO gets passed by reference to bar and maintains its type bar: cmds: - 'echo {{index .FOO 0}}' # <-- FOO is still a map so the task outputs 'A' as expected ``` ::: This also works the same way when calling `deps` and when defining a variable and can be used in any combination: ```yaml version: 3 tasks: foo: vars: FOO: [A, B, C] # <-- FOO is defined as an array BAR: ref: .FOO # <-- BAR is defined as a reference to FOO deps: - task: bar vars: BAR: ref: .BAR # <-- BAR gets passed by reference to bar and maintains its type bar: cmds: - 'echo {{index .BAR 0}}' # <-- BAR still refers to FOO so the task outputs 'A' ``` All references use the same templating syntax as regular templates, so in addition to calling `.FOO`, you can also pass subkeys (`.FOO.BAR`) or indexes (`index .FOO 0`) and use functions (`len .FOO`) as described in the [templating-reference][templating-reference]: ```yaml version: 3 tasks: foo: vars: FOO: [A, B, C] # <-- FOO is defined as an array cmds: - task: bar vars: FOO: ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar bar: cmds: - 'echo {{.FOO}}' # <-- FOO is just the letter 'A' ``` ### Parsing JSON/YAML into map variables If you have a raw JSON or YAML string that you want to process in Task, you can use a combination of the `ref` keyword and the `fromJson` or `fromYaml` templating functions to parse the string into a map variable. For example: ```yaml version: '3' tasks: task-with-map: vars: JSON: '{"a": 1, "b": 2, "c": 3}' FOO: ref: 'fromJson .JSON' cmds: - echo {{.FOO}} ``` ```txt map[a:1 b:2 c:3] ``` ### Secret variables Task supports marking variables as `secret` to prevent their values from being displayed in command logs. When a variable is marked as secret, its value will be replaced with `*****` in the task output logs. ::: warning **Security Notice**: This feature helps prevent accidental exposure of secrets in logs, but is **not a substitute** for proper secret management practices. **What this protects:** * ✅ Secret values in console/terminal logs * ✅ Secret values in CI/CD logs * ✅ Accidental copy-paste of logs containing secrets **What this does NOT protect:** * ❌ Secrets visible in process inspection (e.g., `ps aux`) * ❌ Secrets in shell history * ❌ Secrets in command output (stdout/stderr) * ❌ Secret values copied into derived (non-secret) variables Always use proper secret management tools (HashiCorp Vault, AWS Secrets Manager, etc.) for production environments. ::: To mark a variable as secret, add `secret: true` to the variable definition: ```yaml version: '3' vars: API_KEY: value: 'sk-1234567890abcdef' secret: true tasks: deploy: cmds: - curl -H "Authorization: {{.API_KEY}}" api.example.com # Logged as: task: [deploy] curl -H "Authorization: *****" api.example.com ``` Secret variables work with all variable types: ::: code-group ```yaml [Simple Value] version: '3' vars: PASSWORD: value: 'my-secret-password' secret: true tasks: connect: cmds: - psql -U user -p {{.PASSWORD}} mydb # Logged as: psql -U user -p ***** mydb ``` ```yaml [Shell Command] version: '3' vars: DB_PASSWORD: sh: vault read -field=password secret/db secret: true tasks: migrate: cmds: - psql -U admin -p {{.DB_PASSWORD}} mydb # Password from vault is masked in logs ``` ```yaml [Task-Level Secret] version: '3' vars: PUBLIC_URL: https://example.com tasks: deploy: vars: DEPLOY_TOKEN: value: 'secret-token-123' secret: true cmds: - echo "Deploying to {{.PUBLIC_URL}} with token {{.DEPLOY_TOKEN}}" # Logged as: echo "Deploying to https://example.com with token *****" ``` ::: Multiple secrets in the same command are all masked: ```yaml version: '3' vars: API_KEY: value: 'api-key-123' secret: true PASSWORD: value: 'password-456' secret: true tasks: setup: cmds: - ./setup.sh --api {{.API_KEY}} --pwd {{.PASSWORD}} # Logged as: ./setup.sh --api ***** --pwd ***** ``` ::: tip **Best practices for secret variables:** 1. **Use shell commands to load secrets**, not hardcoded values: ```yaml # ❌ BAD - Secret visible in Taskfile vars: API_KEY: value: 'hardcoded-secret' secret: true # ✅ GOOD - Secret loaded from external source vars: API_KEY: sh: vault kv get -field=api_key secret/myapp secret: true ``` 2. **Combine with environment variables:** ```yaml vars: API_KEY: sh: echo $MY_API_KEY secret: true ``` 3. **Use .gitignore for secret files:** If you use dotenv files, add them to `.gitignore`: ```yaml dotenv: ['.env.local'] # Load from .env.local (in .gitignore) ``` ::: ::: warning **Secrets are not propagated to derived variables.** The `secret` flag only masks the variable it is set on. A non-secret variable that references a secret will expose the resolved value in logs: ```yaml version: '3' vars: API_KEY: value: 'secret-api-key-123' secret: true HEADER: value: 'Bearer {{.API_KEY}}' # ❌ not marked as secret tasks: call: cmds: - curl -H "{{.HEADER}}" api.example.com # Logged as: curl -H "Bearer secret-api-key-123" api.example.com (LEAK) ``` Mark every variable that carries a secret value as `secret: true`: ```yaml vars: HEADER: value: 'Bearer {{.API_KEY}}' secret: true # ✅ masked ``` ::: ## Looping over values Task allows you to loop over certain values and execute a command for each. There are a number of ways to do this depending on the type of value you want to loop over. ### Looping over a static list The simplest kind of loop is an explicit one. This is useful when you want to loop over a set of values that are known ahead of time. ```yaml version: '3' tasks: default: cmds: - for: ['foo.txt', 'bar.txt'] cmd: cat {{ .ITEM }} ``` ### Looping over a matrix If you need to loop over all permutations of multiple lists, you can use the `matrix` property. This should be familiar to anyone who has used a matrix in a CI/CD pipeline. ```yaml version: '3' tasks: default: silent: true cmds: - for: matrix: OS: ['windows', 'linux', 'darwin'] ARCH: ['amd64', 'arm64'] cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}" ``` This will output: ```txt windows/amd64 windows/arm64 linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 ``` You can also use references to other variables as long as they are also lists: ```yaml version: '3' vars: OS_VAR: ['windows', 'linux', 'darwin'] ARCH_VAR: ['amd64', 'arm64'] tasks: default: cmds: - for: matrix: OS: ref: .OS_VAR ARCH: ref: .ARCH_VAR cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}" ``` ### Looping over your task's sources or generated files You are also able to loop over the sources of your task or the files it generates: ::: code-group ```yaml [Sources] version: '3' tasks: default: sources: - foo.txt - bar.txt cmds: - for: sources cmd: cat {{ .ITEM }} ``` ```yaml [Generates] version: '3' tasks: default: generates: - foo.txt - bar.txt cmds: - for: generates cmd: cat {{ .ITEM }} ``` ::: This will also work if you use globbing syntax in `sources` or `generates`. For example, if you specify a source for `*.txt`, the loop will iterate over all files that match that glob. Paths will always be returned as paths relative to the task directory. If you need to convert this to an absolute path, you can use the built-in `joinPath` function. There are some [special variables](/docs/reference/templating#special-variables) that you may find useful for this. ::: code-group ```yaml [Sources] version: '3' tasks: default: vars: MY_DIR: /path/to/dir dir: '{{.MY_DIR}}' sources: - foo.txt - bar.txt cmds: - for: sources cmd: cat {{joinPath .MY_DIR .ITEM}} ``` ```yaml [Generates] version: '3' tasks: default: vars: MY_DIR: /path/to/dir dir: '{{.MY_DIR}}' generates: - foo.txt - bar.txt cmds: - for: generates cmd: cat {{joinPath .MY_DIR .ITEM}} ``` ::: ### Looping over variables To loop over the contents of a variable, use the `var` key followed by the name of the variable you want to loop over. By default, string variables will be split on any whitespace characters. ```yaml version: '3' tasks: default: vars: MY_VAR: foo.txt bar.txt cmds: - for: { var: MY_VAR } cmd: cat {{.ITEM}} ``` If you need to split a string on a different character, you can do this by specifying the `split` property: ```yaml version: '3' tasks: default: vars: MY_VAR: foo.txt,bar.txt cmds: - for: { var: MY_VAR, split: ',' } cmd: cat {{.ITEM}} ``` You can also loop over arrays and maps directly: ```yaml version: 3 tasks: foo: vars: LIST: [foo, bar, baz] cmds: - for: var: LIST cmd: echo {{.ITEM}} ``` When looping over a map we also make an additional `{{.KEY}}` variable available that holds the string value of the map key. Remember that maps are unordered, so the order in which the items are looped over is random. All of this also works with dynamic variables! ```yaml version: '3' tasks: default: vars: MY_VAR: sh: find -type f -name '*.txt' cmds: - for: { var: MY_VAR } cmd: cat {{.ITEM}} ``` ### Renaming variables If you want to rename the iterator variable to make it clearer what the value contains, you can do so by specifying the `as` property: ```yaml version: '3' tasks: default: vars: MY_VAR: foo.txt bar.txt cmds: - for: { var: MY_VAR, as: FILE } cmd: cat {{.FILE}} ``` ### Looping over tasks Because the `for` property is defined at the `cmds` level, you can also use it alongside the `task` keyword to run tasks multiple times with different variables. ```yaml version: '3' tasks: default: cmds: - for: [foo, bar] task: my-task vars: FILE: '{{.ITEM}}' my-task: cmds: - echo '{{.FILE}}' ``` Or if you want to run different tasks depending on the value of the loop: ```yaml version: '3' tasks: default: cmds: - for: [foo, bar] task: task-{{.ITEM}} task-foo: cmds: - echo 'foo' task-bar: cmds: - echo 'bar' ``` ### Looping over dependencies All of the above looping techniques can also be applied to the `deps` property. This allows you to combine loops with concurrency: ```yaml version: '3' tasks: default: deps: - for: [foo, bar] task: my-task vars: FILE: '{{.ITEM}}' my-task: cmds: - echo '{{.FILE}}' ``` It is important to note that as `deps` are run in parallel, the order in which the iterations are run is not guaranteed and the output may vary. For example, the output of the above example may be either: ```shell foo bar ``` or ```shell bar foo ``` ## Forwarding CLI arguments to commands If `--` is given in the CLI, all following parameters are added to a special `.CLI_ARGS` variable. This is useful to forward arguments to another command. The below example will run `yarn install`. ```shell $ task yarn -- install ``` ```yaml version: '3' tasks: yarn: cmds: - yarn {{.CLI_ARGS}} ``` ## Wildcard arguments Another way to parse arguments into a task is to use a wildcard in your task's name. Wildcards are denoted by an asterisk (`*`) and can be used multiple times in a task's name to pass in multiple arguments. Matching arguments will be captured and stored in the `.MATCH` variable and can then be used in your task's commands like any other variable. This variable is an array of strings and so will need to be indexed to access the individual arguments. We suggest creating a named variable for each argument to make it clear what they contain: ```yaml version: '3' tasks: start:*:*: vars: SERVICE: '{{index .MATCH 0}}' REPLICAS: '{{index .MATCH 1}}' cmds: - echo "Starting {{.SERVICE}} with {{.REPLICAS}} replicas" start:*: vars: SERVICE: '{{index .MATCH 0}}' cmds: - echo "Starting {{.SERVICE}}" ``` This call matches the `start:*` task and the string "foo" is captured by the wildcard and stored in the `.MATCH` variable. We then index the `.MATCH` array and store the result in the `.SERVICE` variable which is then echoed out in the cmds: ```shell $ task start:foo Starting foo ``` You can use whitespace in your arguments as long as you quote the task name: ```shell $ task "start:foo bar" Starting foo bar ``` If multiple matching tasks are found, the first one listed in the Taskfile will be used. If you are using included Taskfiles, tasks in parent files will be considered first. ```shell $ task start:foo:3 Starting foo with 3 replicas ``` Using wildcards with aliases Wildcards also work with aliases. If a task has an alias, you can use the alias name with wildcards to capture arguments. For example: ```yaml version: '3' tasks: start:*: aliases: [run:*] vars: SERVICE: "{{index .MATCH 0}}" cmds: - echo "Running {{.SERVICE}}" ``` In this example, you can call the task using the alias run:\*: ```shell $ task run:foo Running foo ``` ## Doing task cleanup with `defer` With the `defer` keyword, it's possible to schedule cleanup to be run once the task finishes. The difference with just putting it as the last command is that this command will run even when the task fails. In the example below, `rm -rf tmpdir/` will run even if the third command fails: ```yaml version: '3' tasks: default: cmds: - mkdir -p tmpdir/ - defer: rm -rf tmpdir/ - echo 'Do work on tmpdir/' ``` If you want to move the cleanup command into another task, that is possible as well: ```yaml version: '3' tasks: default: cmds: - mkdir -p tmpdir/ - defer: { task: cleanup } - echo 'Do work on tmpdir/' cleanup: rm -rf tmpdir/ ``` ::: info Due to the nature of how the [Go's own `defer` work](https://go.dev/tour/flowcontrol/13), the deferred commands are executed in the reverse order if you schedule multiple of them. ::: A special variable `.EXIT_CODE` is exposed when a command exited with a non-zero [exit code](/docs/reference/cli#exit-codes). You can check its presence to know if the task completed successfully or not: ```yaml version: '3' tasks: default: cmds: - defer: echo '{{if .EXIT_CODE}}Failed with {{.EXIT_CODE}}!{{else}}Success!{{end}}' - exit 1 ``` ## Help Running `task --list` (or `task -l`) lists all tasks with a description. The following Taskfile: ```yaml version: '3' tasks: build: desc: Build the go binary. cmds: - go build -v -i main.go test: desc: Run all the go tests. cmds: - go test -race ./... js: cmds: - esbuild --bundle --minify js/index.js > public/bundle.js css: cmds: - esbuild --bundle --minify css/index.css > public/bundle.css ``` would print the following output: ```shell * build: Build the go binary. * test: Run all the go tests. ``` If you want to see all tasks, there's a `--list-all` (alias `-a`) flag as well. ## Display summary of task Running `task --summary task-name` will show a summary of a task. The following Taskfile: ```yaml version: '3' tasks: release: deps: [build] summary: | Release your project to github It will build your project before starting the release. Please make sure that you have set GITHUB_TOKEN before starting. cmds: - your-release-tool build: cmds: - your-build-tool ``` with running `task --summary release` would print the following output: ``` task: release Release your project to github It will build your project before starting the release. Please make sure that you have set GITHUB_TOKEN before starting. dependencies: - build commands: - your-release-tool ``` If a summary is missing, the description will be printed. If the task does not have a summary or a description, a warning is printed. Please note: *showing the summary will not execute the command*. ## Task aliases Aliases are alternative names for tasks. They can be used to make it easier and quicker to run tasks with long or hard-to-type names. You can use them on the command line, when [calling sub-tasks](#calling-another-task) in your Taskfile and when [including tasks](#including-other-taskfiles) with aliases from another Taskfile. They can also be used together with [namespace aliases](#namespace-aliases). ```yaml version: '3' tasks: generate: aliases: [gen] cmds: - task: gen-mocks generate-mocks: aliases: [gen-mocks] cmds: - echo "generating..." ``` ## Overriding task name Sometimes you may want to override the task name printed on the summary, up-to-date messages to STDOUT, etc. In this case, you can just set `label:`, which can also be interpolated with variables: ```yaml version: '3' tasks: default: cmds: - task: print vars: MESSAGE: hello - task: print vars: MESSAGE: world print: label: 'print-{{.MESSAGE}}' cmds: - echo "{{.MESSAGE}}" ``` ## Warning Prompts Warning Prompts are used to prompt a user for confirmation before a task is executed. Below is an example using `prompt` with a dangerous command, that is called between two safe commands: ```yaml version: '3' tasks: example: cmds: - task: not-dangerous - task: dangerous - task: another-not-dangerous not-dangerous: cmds: - echo 'not dangerous command' another-not-dangerous: cmds: - echo 'another not dangerous command' dangerous: prompt: This is a dangerous command... Do you want to continue? cmds: - echo 'dangerous command' ``` ```shell ❯ task dangerous task: "This is a dangerous command... Do you want to continue?" [y/N] ``` Prompts can be a single value or a list of prompts, like below: ```yaml version: '3' tasks: example: cmds: - task: dangerous dangerous: prompt: - This is a dangerous command... Do you want to continue? - Are you sure? cmds: - echo 'dangerous command' ``` Warning prompts are called before executing a task. If a prompt is denied Task will exit with [exit code](/docs/reference/cli#exit-codes) 205. If approved, Task will continue as normal. ```shell ❯ task example not dangerous command task: "This is a dangerous command. Do you want to continue?" [y/N] y dangerous command another not dangerous command ``` To skip warning prompts automatically, you can use the `--yes` (alias `-y`) option when calling the task. By including this option, all warnings, will be automatically confirmed, and no prompts will be shown. ::: warning Tasks with prompts always fail by default on non-terminal environments, like a CI, where an `stdin` won't be available for the user to answer. In those cases, use `--yes` (`-y`) to force all tasks with a prompt to run. ::: ## Silent mode Silent mode disables the echoing of commands before Task runs it. For the following Taskfile: ```yaml version: '3' tasks: echo: cmds: - echo "Print something" ``` Normally this will be printed: ```shell echo "Print something" Print something ``` With silent mode on, the below will be printed instead: ```shell Print something ``` There are four ways to enable silent mode: * At command level: ```yaml version: '3' tasks: echo: cmds: - cmd: echo "Print something" silent: true ``` * At task level: ```yaml version: '3' tasks: echo: cmds: - echo "Print something" silent: true ``` * Globally at Taskfile level: ```yaml version: '3' silent: true tasks: echo: cmds: - echo "Print something" ``` * Or globally with `--silent` or `-s` flag If you want to suppress STDOUT instead, just redirect a command to `/dev/null`: ```yaml version: '3' tasks: echo: cmds: - echo "This will print nothing" > /dev/null ``` ## Dry run mode Dry run mode (`--dry`) compiles and steps through each task, printing the commands that would be run without executing them. This is useful for debugging your Taskfiles. ## Ignore errors You have the option to ignore errors during command execution. Given the following Taskfile: ```yaml version: '3' tasks: echo: cmds: - exit 1 - echo "Hello World" ``` Task will abort the execution after running `exit 1` because the status code `1` stands for `EXIT_FAILURE`. However, it is possible to continue with execution using `ignore_error`: ```yaml version: '3' tasks: echo: cmds: - cmd: exit 1 ignore_error: true - echo "Hello World" ``` `ignore_error` can also be set for a task, which means errors will be suppressed for all commands. Nevertheless, keep in mind that this option will not propagate to other tasks called either by `deps` or `cmds`! ## Output syntax By default, Task just redirects the STDOUT and STDERR of the running commands to the shell in real-time. This is good for having live feedback for logging printed by commands, but the output can become messy if you have multiple commands running simultaneously and printing lots of stuff. To make this more customizable, there are currently three different output options you can choose: * `interleaved` (default) * `group` * `prefixed` To choose another one, just set it to root in the Taskfile: ```yaml version: '3' output: 'group' tasks: # ... ``` The `group` output will print the entire output of a command once after it finishes, so you will not have live feedback for commands that take a long time to run. When using the `group` output, you can optionally provide a templated message to print at the start and end of the group. This can be useful for instructing CI systems to group all of the output for a given task, such as with [GitHub Actions' `::group::` command](https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions#grouping-log-lines) or [Azure Pipelines](https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?expand=1\&view=azure-devops\&tabs=bash#formatting-commands). ```yaml version: '3' output: group: begin: '::group::{{.TASK}}' end: '::endgroup::' tasks: default: cmds: - echo 'Hello, World!' silent: true ``` ```shell $ task default ::group::default Hello, World! ::endgroup:: ``` When using the `group` output, you may swallow the output of the executed command on standard output and standard error if it does not fail (zero exit code). ```yaml version: '3' silent: true output: group: error_only: true tasks: passes: echo 'output-of-passes' errors: echo 'output-of-errors' && exit 1 ``` ```shell $ task passes $ task errors output-of-errors task: Failed to run task "errors": exit status 1 ``` The `prefix` output will prefix every line printed by a command with `[task-name] ` as the prefix, but you can customize the prefix for a command with the `prefix:` attribute: ```yaml version: '3' output: prefixed tasks: default: deps: - task: print vars: { TEXT: foo } - task: print vars: { TEXT: bar } - task: print vars: { TEXT: baz } print: cmds: - echo "{{.TEXT}}" prefix: 'print-{{.TEXT}}' silent: true ``` ```shell $ task default [print-foo] foo [print-bar] bar [print-baz] baz ``` ::: tip The `output` option can also be specified by the `--output` or `-o` flags. ::: ## CI Integration ### Colored output Task automatically enables colored output when running in CI environments (`CI=true`). Most CI providers set this variable automatically. You can also force colored output with `FORCE_COLOR=1` or disable it with `NO_COLOR=1`. ### Error annotations When running in GitHub Actions (`GITHUB_ACTIONS=true`), Task automatically emits error annotations when a task fails. These annotations appear in the workflow summary, making it easier to spot failures without scrolling through logs. ```shell ::error title=Task 'build' failed::exit status 1 ``` This feature requires no configuration and works automatically. ## Interactive CLI application When running interactive CLI applications inside Task they can sometimes behave weirdly, especially when the [output mode](#output-syntax) is set to something other than `interleaved` (the default), or when interactive apps are run in parallel with other tasks. The `interactive: true` tells Task this is an interactive application and Task will try to optimize for it: ```yaml version: '3' tasks: default: cmds: - vim my-file.txt interactive: true ``` If you still have problems running an interactive app through Task, please open an issue about it. ## Short task syntax Starting on Task v3, you can now write tasks with a shorter syntax if they have the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc): ```yaml version: '3' tasks: build: go build -v -o ./app{{exeExt}} . run: - task: build - ./app{{exeExt}} -h localhost -p 8080 ``` ## `set` and `shopt` It's possible to specify options to the [`set`](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html) and [`shopt`](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html) builtins. This can be added at global, task or command level. ```yaml version: '3' set: [pipefail] shopt: [globstar] tasks: # `globstar` required for double star globs to work default: echo **/*.go ``` ::: info Keep in mind that not all options are available in the [shell interpreter library](https://github.com/mvdan/sh) that Task uses. ::: ## Watch tasks With the flags `--watch` or `-w` task will watch for file changes and run the task again. This requires the `sources` attribute to be given, so task knows which files to watch. The default watch interval is 100 milliseconds, but it's possible to change it by either setting `interval: '500ms'` in the root of the Taskfile or by passing it as an argument like `--interval=500ms`. This interval is the time Task will wait for duplicated events. It will only run the task again once, even if multiple changes happen within the interval. Also, it's possible to set `watch: true` in a given task and it'll automatically run in watch mode: ```yaml version: '3' interval: 500ms tasks: build: desc: Builds the Go application watch: true sources: - '**/*.go' cmds: - go build # ... ``` ::: info Note that when setting `watch: true` to a task, it'll only run in watch mode when running from the CLI via `task my-watch-task`, but won't run in watch mode if called by another task, either directly or as a dependency. ::: ::: warning The watcher can misbehave in certain scenarios, in particular for long-running servers. There is a [known bug](https://github.com/go-task/task/issues/160) where child processes of the running might not be killed appropriately. It's advised to avoid running commands as `go run` and prefer `go build [...] && ./binary` instead. If you are having issues, you might want to try tools specifically designed for live-reloading, like [Air](https://github.com/air-verse/air/). Also, be sure to [report any issues](https://github.com/go-task/task/issues/new?template=bug_report.yml) to us. ::: [config]: /docs/reference/config [gotemplate]: https://golang.org/pkg/text/template/ [templating-reference]: /docs/reference/templating --- --- url: /docs/reference/schema.md description: A reference for the Taskfile schema --- # Taskfile Schema Reference This page documents all available properties and types for the Taskfile schema version 3, based on the [official JSON schema](https://taskfile.dev/schema.json). ## Root Schema The root Taskfile schema defines the structure of your main `Taskfile.yml`. ### `version` * **Type**: `string` or `number` * **Required**: Yes * **Valid values**: `"3"`, `3`, or any valid semver string * **Description**: Version of the Taskfile schema ```yaml version: '3' ``` ### `output` * **Type**: `string` or `object` * **Default**: `interleaved` * **Options**: `interleaved`, `group`, `prefixed` * **Description**: Controls how task output is displayed ```yaml # Simple string format output: group # Advanced object format output: group: begin: "::group::{{.TASK}}" end: "::endgroup::" error_only: false ``` ### `method` * **Type**: `string` * **Default**: `checksum` * **Options**: `checksum`, `timestamp`, `none` * **Description**: Default method for checking if tasks are up-to-date ```yaml method: timestamp ``` ### [`includes`](#include) * **Type**: `map[string]Include` * **Description**: Include other Taskfiles ```yaml includes: # Simple string format docs: ./Taskfile.yml # Full object format backend: taskfile: ./backend dir: ./backend optional: false flatten: false internal: false aliases: [api] excludes: [internal-task] vars: SERVICE_NAME: backend checksum: abc123... ``` ### [`vars`](#variable) * **Type**: `map[string]Variable` * **Description**: Global variables available to all tasks ```yaml vars: # Simple values APP_NAME: myapp VERSION: 1.0.0 DEBUG: true PORT: 8080 FEATURES: [auth, logging] # Dynamic variables COMMIT_HASH: sh: git rev-parse HEAD # Variable references BUILD_VERSION: ref: .VERSION # Map variables CONFIG: map: database: postgres cache: redis ``` ### `env` * **Type**: `map[string]Variable` * **Description**: Global environment variables ```yaml env: NODE_ENV: production DATABASE_URL: sh: echo $DATABASE_URL ``` ### [`tasks`](#task) * **Type**: `map[string]Task` * **Description**: Task definitions ```yaml tasks: # Simple string format hello: echo "Hello World" # Array format build: - go mod tidy - go build ./... # Full object format deploy: desc: Deploy the application cmds: - ./scripts/deploy.sh ``` ### `silent` * **Type**: `bool` * **Default**: `false` * **Description**: Suppress task name and command output by default ```yaml silent: true ``` ### `dotenv` * **Type**: `[]string` * **Description**: Load environment variables from .env files. When the same variable is defined in multiple files, the first file in the list takes precedence. ```yaml dotenv: - .env.local # Highest priority - .env # Lowest priority ``` ### `run` * **Type**: `string` * **Default**: `always` * **Options**: `always`, `once`, `when_changed` * **Description**: Default execution behavior for tasks ```yaml run: once ``` ### `interval` * **Type**: `string` * **Default**: `100ms` * **Pattern**: `^[0-9]+(?:m|s|ms)$` * **Description**: Watch interval for file changes ```yaml interval: 1s ``` ### `set` * **Type**: `[]string` * **Options**: `allexport`, `a`, `errexit`, `e`, `noexec`, `n`, `noglob`, `f`, `nounset`, `u`, `xtrace`, `x`, `pipefail` * **Description**: POSIX shell options for all commands ```yaml set: [errexit, nounset, pipefail] ``` ### `shopt` * **Type**: `[]string` * **Options**: `expand_aliases`, `globstar`, `nullglob` * **Description**: Bash shell options for all commands ```yaml shopt: [globstar] ``` ## Include Configuration for including external Taskfiles. ### `taskfile` * **Type**: `string` * **Required**: Yes * **Description**: Path to the Taskfile or directory to include ```yaml includes: backend: ./backend/Taskfile.yml # Shorthand for above frontend: ./frontend ``` ### `dir` * **Type**: `string` * **Description**: Working directory for included tasks ```yaml includes: api: taskfile: ./api dir: ./api ``` ### `optional` * **Type**: `bool` * **Default**: `false` * **Description**: Don't error if the included file doesn't exist ```yaml includes: optional-tasks: taskfile: ./optional.yml optional: true ``` ### `flatten` * **Type**: `bool` * **Default**: `false` * **Description**: Include tasks without namespace prefix ```yaml includes: common: taskfile: ./common.yml flatten: true ``` ### `internal` * **Type**: `bool` * **Default**: `false` * **Description**: Hide included tasks from command line and `--list` ```yaml includes: internal: taskfile: ./internal.yml internal: true [...] tasks: example: desc: using an internal task cmds: - task: internal:default ``` ### `aliases` * **Type**: `[]string` * **Description**: Alternative names for the namespace ```yaml includes: database: taskfile: ./db.yml aliases: [db, data] ``` ### `excludes` * **Type**: `[]string` * **Description**: Tasks to exclude from inclusion ```yaml includes: shared: taskfile: ./shared.yml excludes: [internal-setup, debug-only] ``` ### `vars` * **Type**: `map[string]Variable` * **Description**: Variables to pass to the included Taskfile ```yaml includes: deploy: taskfile: ./deploy.yml vars: ENVIRONMENT: production ``` ### `checksum` * **Type**: `string` * **Description**: Expected checksum of the included file ```yaml includes: remote: taskfile: https://example.com/tasks.yml checksum: c153e97e0b3a998a7ed2e61064c6ddaddd0de0c525feefd6bba8569827d8efe9 ``` ## Variable Variables support multiple types and can be static values, dynamic commands, references, or maps. ### Static Variables ```yaml vars: # String APP_NAME: myapp # Number PORT: 8080 # Boolean DEBUG: true # Array FEATURES: [auth, logging, metrics] # Null OPTIONAL_VAR: null ``` ### Dynamic Variables (`sh`) ```yaml vars: COMMIT_HASH: sh: git rev-parse HEAD BUILD_TIME: sh: date -u +"%Y-%m-%dT%H:%M:%SZ" ``` ### Variable References (`ref`) ```yaml vars: BASE_VERSION: 1.0.0 FULL_VERSION: ref: .BASE_VERSION ``` ### Map Variables (`map`) ```yaml vars: CONFIG: map: database: host: localhost port: 5432 cache: type: redis ttl: 3600 ``` ### Secret Variables (`secret`) Mark variables as secret to mask their values in command logs. ```yaml vars: API_KEY: value: 'sk-1234567890abcdef' secret: true # This variable will be masked in logs DB_PASSWORD: sh: vault read -field=password secret/db secret: true # Works with dynamic variables too ``` When a variable is marked as `secret: true`, Task will replace its value with `*****` in command logs. The actual command execution still receives the real value. ::: info For complete documentation on secret variables, including security considerations and best practices, see the [Secret variables](/docs/guide#secret-variables) section in the Guide. ::: ### Variable Ordering Variables can reference previously defined variables: ```yaml vars: GREETING: Hello TARGET: World MESSAGE: '{{.GREETING}} {{.TARGET}}!' ``` ## Task Individual task configuration with multiple syntax options. ### Simple Task Formats ```yaml tasks: # String command hello: echo "Hello World" # Array of commands build: - go mod tidy - go build ./... # Object with cmd shorthand test: cmd: go test ./... ``` ### Task Properties #### `cmds` * **Type**: `[]Command` * **Description**: Commands to execute ```yaml tasks: build: cmds: - go build ./... - echo "Build complete" ``` #### `cmd` * **Type**: `string` * **Description**: Single command (alternative to `cmds`) ```yaml tasks: test: cmd: go test ./... ``` #### `deps` * **Type**: `[]Dependency` * **Description**: Tasks to run before this task ```yaml tasks: # Simple dependencies deploy: deps: [build, test] cmds: - ./deploy.sh # Dependencies with variables advanced-deploy: deps: - task: build vars: ENVIRONMENT: production - task: test vars: COVERAGE: true cmds: - ./deploy.sh # Silent dependencies main: deps: - task: setup silent: true cmds: - echo "Main task" # Loop dependencies test-all: deps: - for: [unit, integration, e2e] task: test vars: TEST_TYPE: '{{.ITEM}}' cmds: - echo "All tests completed" ``` #### `desc` * **Type**: `string` * **Description**: Short description shown in `--list` ```yaml tasks: test: desc: Run unit tests cmds: - go test ./... ``` #### `summary` * **Type**: `string` * **Description**: Detailed description shown in `--summary` ```yaml tasks: deploy: desc: Deploy to production summary: | Deploy the application to production environment. This includes building, testing, and uploading artifacts. ``` #### `prompt` * **Type**: `string` or `[]string` * **Description**: Prompts shown before task execution ```yaml tasks: # Single prompt deploy: prompt: "Deploy to production?" cmds: - ./deploy.sh # Multiple prompts deploy-multi: prompt: - "Are you sure?" - "This will affect live users!" cmds: - ./deploy.sh ``` #### `aliases` * **Type**: `[]string` * **Description**: Alternative names for the task ```yaml tasks: build: aliases: [compile, make] cmds: - go build ./... ``` #### `method` * **Type**: `string` * **Default**: `checksum` * **Options**: `checksum`, `timestamp`, `none` * **Description**: Method for checking if the task is up-to-date. Refer to the `method` root property for details. ```yaml tasks: build: sources: - go.mod method: timestamp ``` #### `sources` * **Type**: `[]string` or `[]Glob` * **Description**: Source files to monitor for changes ```yaml tasks: build: sources: - '**/*.go' - go.mod # With exclusions - exclude: '**/*_test.go' cmds: - go build ./... ``` #### `generates` * **Type**: `[]string` or `[]Glob` * **Description**: Files generated by this task ```yaml tasks: build: sources: ['**/*.go'] generates: - './app' - exclude: '*.debug' cmds: - go build -o app ./cmd ``` #### `status` * **Type**: `[]string` * **Description**: Commands to check if task should run ```yaml tasks: install-deps: status: - test -f node_modules/.installed cmds: - npm install - touch node_modules/.installed ``` #### `preconditions` * **Type**: `[]Precondition` * **Description**: Conditions that must be met before running ```yaml tasks: # Simple precondition (shorthand) build: preconditions: - test -d ./src cmds: - go build ./... # Preconditions with custom messages deploy: preconditions: - sh: test -n "$API_KEY" msg: 'API_KEY environment variable is required' - sh: test -f ./app msg: "Application binary not found. Run 'task build' first." cmds: - ./deploy.sh ``` #### `if` * **Type**: `string` * **Description**: Shell command to conditionally execute the task. If the command exits with a non-zero code, the task is skipped (not failed). ```yaml tasks: # Task only runs in CI environment deploy: if: '[ "$CI" = "true" ]' cmds: - ./deploy.sh # Using Go template expressions build-prod: if: '{{eq .ENV "production"}}' cmds: - go build -ldflags="-s -w" ./... ``` #### `dir` * **Type**: `string` * **Description**: The directory in which this task should run * **Default**: If the task is in the root Taskfile, the default `dir` is `ROOT_DIR`. For included Taskfiles, the default `dir` is the value specified in their respective `includes.*.dir` field (if any). ```yaml tasks: current-dir: dir: '{{.USER_WORKING_DIR}}' cmd: pwd ``` #### `requires` * **Type**: `Requires` * **Description**: Required variables with optional enum validation ```yaml tasks: deploy: requires: vars: [API_KEY, ENVIRONMENT] cmds: - ./deploy.sh advanced-deploy: requires: vars: - API_KEY - name: ENVIRONMENT enum: [development, staging, production] - name: LOG_LEVEL enum: [debug, info, warn, error] cmds: - echo "Deploying to {{.ENVIRONMENT}} with log level {{.LOG_LEVEL}}" - ./deploy.sh # Requirements with enum from variable reference reusable-deploy: requires: vars: - name: ENVIRONMENT enum: ref: .ALLOWED_ENVS cmds: - ./deploy.sh ``` See [Prompting for missing variables interactively](/docs/guide#prompting-for-missing-variables-interactively) for information on enabling interactive prompts for missing required variables. #### `watch` * **Type**: `bool` * **Default**: `false` * **Description**: Automatically run task in watch mode ```yaml tasks: dev: watch: true cmds: - npm run dev ``` #### `platforms` * **Type**: `[]string` * **Description**: Platforms where this task should run ```yaml tasks: windows-build: platforms: [windows] cmds: - go build -o app.exe ./cmd unix-build: platforms: [linux, darwin] cmds: - go build -o app ./cmd ``` ## Command Individual command configuration within a task. ### Basic Commands ```yaml tasks: example: cmds: - echo "Simple command" - ls -la ``` ### Command Object ```yaml tasks: example: cmds: - cmd: echo "Hello World" silent: true ignore_error: false platforms: [linux, darwin] set: [errexit] shopt: [globstar] ``` ### Task References ```yaml tasks: example: cmds: - task: other-task vars: PARAM: value silent: false ``` ### Deferred Commands ```yaml tasks: with-cleanup: cmds: - echo "Starting work" # Deferred command string - defer: echo "Cleaning up" # Deferred task reference - defer: task: cleanup-task vars: CLEANUP_MODE: full ``` ### For Loops #### Loop Over List ```yaml tasks: greet-all: cmds: - for: [alice, bob, charlie] cmd: echo "Hello {{.ITEM}}" ``` #### Loop Over Sources/Generates ```yaml tasks: process-files: sources: ['*.txt'] cmds: - for: sources cmd: wc -l {{.ITEM}} - for: generates cmd: gzip {{.ITEM}} ``` #### Loop Over Variable ```yaml tasks: process-items: vars: ITEMS: 'item1,item2,item3' cmds: - for: var: ITEMS split: ',' as: CURRENT cmd: echo "Processing {{.CURRENT}}" ``` #### Loop Over Matrix ```yaml tasks: test-matrix: cmds: - for: matrix: OS: [linux, windows, darwin] ARCH: [amd64, arm64] cmd: echo "Testing {{.ITEM.OS}}/{{.ITEM.ARCH}}" ``` #### Loop in Dependencies ```yaml tasks: build-all: deps: - for: [frontend, backend, worker] task: build vars: SERVICE: '{{.ITEM}}' ``` ### Conditional Commands Use `if` to conditionally execute a command. If the shell command exits with a non-zero code, the command is skipped. ```yaml tasks: build: cmds: # Only run in production - cmd: echo "Optimizing for production" if: '[ "$ENV" = "production" ]' # Using Go templates - cmd: echo "Feature enabled" if: '{{eq .ENABLE_FEATURE "true"}}' # Inside for loops (evaluated per iteration) - for: [a, b, c] cmd: echo "processing {{.ITEM}}" if: '[ "{{.ITEM}}" != "b" ]' ``` ## Shell Options ### Set Options Available `set` options for POSIX shell features: * `allexport` / `a` - Export all variables * `errexit` / `e` - Exit on error * `noexec` / `n` - Read commands but don't execute * `noglob` / `f` - Disable pathname expansion * `nounset` / `u` - Error on undefined variables * `xtrace` / `x` - Print commands before execution * `pipefail` - Pipe failures propagate ```yaml # Global level set: [errexit, nounset, pipefail] tasks: debug: # Task level set: [xtrace] cmds: - cmd: echo "This will be traced" # Command level set: [noexec] ``` ### Shopt Options Available `shopt` options for Bash features: * `expand_aliases` - Enable alias expansion * `globstar` - Enable `**` recursive globbing * `nullglob` - Null glob expansion ```yaml # Global level shopt: [globstar] tasks: find-files: # Task level shopt: [nullglob] cmds: - cmd: ls **/*.go # Command level shopt: [globstar] ``` --- --- url: /docs/reference/environment.md description: A reference for the Taskfile environment variables --- # Environment 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](./config.md) * *Environment variables* * [Command-line flags](./cli.md) In this document, we will look at the second of the three options, environment variables. All Task-specific variables are prefixed with `TASK_` and override their configuration file equivalents. ## Variables All [configuration file options](./config.md) can also be set via environment variables. The priority order is: CLI flags > environment variables > config files > defaults. ### `TASK_VERBOSE` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Enable verbose output for all tasks * **Config equivalent**: [`verbose`](./config.md#verbose) ### `TASK_SILENT` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Disables echoing of commands * **Config equivalent**: [`silent`](./config.md#silent) ### `TASK_COLOR` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `true` * **Description**: Enable colored output * **Config equivalent**: [`color`](./config.md#color) ### `TASK_DISABLE_FUZZY` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Disable fuzzy matching for task names * **Config equivalent**: [`disable-fuzzy`](./config.md#disable-fuzzy) ### `TASK_CONCURRENCY` * **Type**: `integer` * **Description**: Limit number of tasks to run concurrently * **Config equivalent**: [`concurrency`](./config.md#concurrency) ### `TASK_FAILFAST` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: When running tasks in parallel, stop all tasks if one fails * **Config equivalent**: [`failfast`](./config.md#failfast) ### `TASK_DRY` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Compiles and prints tasks in the order that they would be run, without executing them ### `TASK_ASSUME_YES` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Assume "yes" as answer to all prompts ### `TASK_INTERACTIVE` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Prompt for missing required variables ### `TASK_OUTPUT` * **Type**: `string` (`interleaved`, `group`, `prefixed`) * **Description**: Sets the output style * **CLI equivalent**: [`--output`](./cli.md#--output-string) ### `TASK_OUTPUT_GROUP_BEGIN` * **Type**: `string` * **Description**: Message template to print before a task's grouped output. Only applies when the output style is `group`. * **CLI equivalent**: [`--output-group-begin`](./cli.md#--output-group-begin-template) ### `TASK_OUTPUT_GROUP_END` * **Type**: `string` * **Description**: Message template to print after a task's grouped output. Only applies when the output style is `group`. * **CLI equivalent**: [`--output-group-end`](./cli.md#--output-group-end-template) ### `TASK_OUTPUT_GROUP_ERROR_ONLY` * **Type**: `boolean` (`true`, `false`, `1`, `0`) * **Default**: `false` * **Description**: Swallow output from successful tasks. Only applies when the output style is `group`. * **CLI equivalent**: [`--output-group-error-only`](./cli.md#--output-group-error-only) ### `TASK_TEMP_DIR` Defines the location of Task's temporary directory which is used for storing checksums and temporary metadata. Can be relative like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. Relative paths are relative to the root Taskfile, not the working directory. Defaults to: `./.task`. ### `TASK_CORE_UTILS` This env controls whether the Bash interpreter will use its own core utilities implemented in Go, or the ones available in the system. Valid values are `true` (`1`) or `false` (`0`). By default, this is `true` on Windows and `false` on other operating systems. We might consider making this enabled by default on all platforms in the future. ### `FORCE_COLOR` Force color output usage. ### Custom Colors All color variables are [ANSI color codes][ansi]. You can specify multiple codes separated by a semicolon. For example: `31;1` will make the text bold and red. Task also supports 8-bit color (256 colors). You can specify these colors by using the sequence `38;2;R:G:B` for foreground colors and `48;2;R:G:B` for background colors where `R`, `G` and `B` should be replaced with values between 0 and 255. For convenience, we allow foreground colors to be specified using shorthand, comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to `38;2;255:0:0`. A table of variables and their defaults can be found below: | ENV | Default | | --------------------------- | ------- | | `TASK_COLOR_RESET` | `0` | | `TASK_COLOR_RED` | `31` | | `TASK_COLOR_GREEN` | `32` | | `TASK_COLOR_YELLOW` | `33` | | `TASK_COLOR_BLUE` | `34` | | `TASK_COLOR_MAGENTA` | `35` | | `TASK_COLOR_CYAN` | `36` | | `TASK_COLOR_BRIGHT_RED` | `91` | | `TASK_COLOR_BRIGHT_GREEN` | `92` | | `TASK_COLOR_BRIGHT_YELLOW` | `93` | | `TASK_COLOR_BRIGHT_BLUE` | `94` | | `TASK_COLOR_BRIGHT_MAGENTA` | `95` | | `TASK_COLOR_BRIGHT_CYAN` | `96` | [ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code --- --- url: /docs/reference/config.md description: Complete reference for the Task config files and env vars --- # 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](./environment.md) * [Command-line flags](./cli.md) 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: ```yaml [$XDG_CONFIG_HOME/task/taskrc.yml] # lowest priority global config option_1: foo option_2: foo option_3: foo ``` ```yaml [$HOME/.taskrc.yml] option_1: bar option_2: bar ``` ```yaml [$HOME/path/to/project/.taskrc.yml] # highest priority project config option_1: baz ``` You would end up with the following configuration: ```yaml 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](../experiments/index.md) for more information. ```yaml experiments: feature_name: 1 another_feature: 2 ``` ### `verbose` * **Type**: `boolean` * **Default**: `false` * **Description**: Enable verbose output for all tasks * **CLI equivalent**: [`-v, --verbose`](./cli.md#-v---verbose) * **Environment variable**: [`TASK_VERBOSE`](./environment.md#task-verbose) ```yaml verbose: true ``` ### `silent` * **Type**: `boolean` * **Default**: `false` * **Description**: Disables echoing of commands * **CLI equivalent**: [`-s, --silent`](./cli.md#-s---silent) * **Environment variable**: [`TASK_SILENT`](./environment.md#task-silent) ```yaml silent: true ``` ### `color` * **Type**: `boolean` * **Default**: `true` * **Description**: Enable colored output. Colors are automatically enabled in CI environments (`CI=true`). * **CLI equivalent**: [`-c, --color`](./cli.md#-c---color) * **Environment variable**: [`TASK_COLOR`](./environment.md#task-color) ```yaml 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`](./cli.md#--disable-fuzzy) * **Environment variable**: [`TASK_DISABLE_FUZZY`](./environment.md#task-disable-fuzzy) ```yaml disable-fuzzy: true ``` ### `concurrency` * **Type**: `integer` * **Minimum**: `1` * **Description**: Number of concurrent tasks to run * **CLI equivalent**: [`-C, --concurrency`](./cli.md#-c---concurrency-number) * **Environment variable**: [`TASK_CONCURRENCY`](./environment.md#task-concurrency) ```yaml concurrency: 4 ``` ### `failfast` * **Type**: `boolean` * **Default**: `false` * **Description**: Stop executing dependencies as soon as one of them fail * **CLI equivalent**: [`-F, --failfast`](./cli.md#-f---failfast) * **Environment variable**: [`TASK_FAILFAST`](./environment.md#task-failfast) ```yaml 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`](./cli.md#--interactive) ```yaml 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`](./environment.md#task-temp-dir) ```yaml temp-dir: .task ``` ## Example Configuration Here's a complete example of a `.taskrc.yml` file with all available options: ```yaml # Global settings verbose: true silent: false color: true disable-fuzzy: false concurrency: 2 temp-dir: .task # Enable experimental features experiments: REMOTE_TASKFILES: 1 ``` --- --- 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](./config.md) * [Environment variables](./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`](./config.md#verbose) * **Environment variable**: [`TASK_VERBOSE`](./environment.md#task-verbose) ```bash task build --verbose ``` #### `-s, --silent` Disable command echoing. * **Config equivalent**: [`silent`](./config.md#silent) * **Environment variable**: [`TASK_SILENT`](./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`](./config.md#disable-fuzzy) * **Environment variable**: [`TASK_DISABLE_FUZZY`](./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`](./config.md#failfast) * **Environment variable**: [`TASK_FAILFAST`](./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`](./environment.md#task-dry) ```bash task deploy --dry ``` #### `-p, --parallel` Execute multiple tasks in parallel. ```bash task test lint --parallel ``` #### `-C, --concurrency ` Limit the number of concurrent tasks. Zero means unlimited. * **Config equivalent**: [`concurrency`](./config.md#concurrency) * **Environment variable**: [`TASK_CONCURRENCY`](./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 ` Set the directory where Task will run and look for Taskfiles. ```bash task build --dir ./backend ``` #### `-t, --taskfile ` 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 ` Set the directory used to store Task temporary files, such as checksums. Relative paths are relative to the root Taskfile. * **Config equivalent**: [`temp-dir`](./config.md#temp-dir) * **Environment variable**: [`TASK_TEMP_DIR`](./environment.md#task-temp-dir) ```bash task build --temp-dir .task-cache ``` ### Output Control #### `-o, --output ` Set output style. Available modes: `interleaved`, `group`, `prefixed`. * **Environment variable**: [`TASK_OUTPUT`](./environment.md#task-output) ```bash task test --output group ``` #### `--output-group-begin