Defining tasks

Poe the Poet supports several ways of defining tasks under [tool.poe.tasks], trading off simplicity against configurability. Furthermore toml syntax supports both more terse or more expressive alternative ways of writing the same thing, see the guide on Using toml syntax for details.

A task defined as a string will by default be interpreted as a single command to be executed without a shell (aka a cmd task).

[tool.poe.tasks]
test = "pytest"

A task defined as an array will by default be interpreted as a sequence of references to other tasks.

[tool.poe.tasks]
test   = "pytest"
_build = "poetry build"
build  = ["test", "_build"] # this task runs the two referenced tasks in sequence

Important

Task with names starting with an underscore _ are excluded from documentation and cannot be run directly from the command line. They can only be run when referenced by another task.

Tasks can also be defined as sub-tables, which allows for specifying the task type and various configuration options on the task. The type of a task defined as a table is determined by the presence of a particular key that is unique to a certain task type and corresponds to the name of the task type.

[tool.poe.tasks.test-quick]
help = "Run tests excluding those makes as slow."
cmd  = "pytest -m \"not slow\"" # here the cmd key identifies the task type and content

This implies that you can also define tasks of other types on a single line, like so:

[tool.poe.tasks]
tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &" } # (posix) shell based task

Some options are applicable to all tasks, whereas other are only applicable to specific types of tasks.

See also

Top level tasks are defined as members of [tool.poe.tasks], but sometimes tasks can be defined as children of other tasks, for example as items within a sequence task, or as the control or case roles with a switch task.

Types of task

You can define seven different types of task:

  • Command tasks cmd : for simple commands that are executed as a subprocess without a shell

  • Script tasks script : for python function calls

  • Shell tasks shell : for scripts to be executed with via an external interpreter (such as sh).

  • Sequence tasks sequence : for composing multiple tasks into a sequence

  • Expression tasks expr : which consist of a python expression to evaluate

  • Switch tasks switch : for running different tasks depending on a control value (such as the platform)

  • Reference tasks ref : for defining a task as an alias of another task, such as in a sequence task.