Poe the Poet

A batteries included task runner that works well with poetry or uv.

📖 Read the documentation 📖

Features

✅ Straight forward declaration of project tasks in your pyproject.toml (or poe_tasks.toml)
✅ Tasks are run in poetry or uv's virtualenv (or another env you specify)
✅ Shell completion of task names and arguments
✅ The poe CLI can be used standalone, or as a plugin for poetry
✅ Tasks can be commands, shell scripts, python expressions, or references to python functions
✅ Concise commands with extra arguments passed to the task poe [options] task [task_args]
✅ Easily declare named CLI arguments for your tasks
✅ Tasks can specify and reference environment variables, even without a shell
✅ Tasks are self documenting, with optional help messages (just run poe with no arguments)
✅ Tasks can be composed to run in sequence, in parallel, or as a DAG.
✅ Works with .env files
✅ Can be used as a library to embed in other tools
✅ Tasks can be defined in python packages for ease of reuse across projects
✅ Also works fine as a general purpose task runner

Quick start

Install the Poe the Poet globally via pipx or another method.

pipx install poethepoet

Or add it as a poetry project plugin:

[tool.poetry.requires-plugins]
poethepoet = ">=0.39"

Define some tasks in your pyproject.toml

[tool.poe.tasks]
test         = "pytest --cov=my_app"                         # a simple command task
serve.script = "my_app.service:run(debug=True)"              # python script based task
tunnel.shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &"   # (posix) shell based task

# A more complete example with documentation and named arguments
[tool.poe.tasks.count-incomplete]
help = "Count incomplete tasks in DynamoDB"
cmd  = """
aws dynamodb scan --table-name tasks
                  --select "COUNT"
                  --filter-expression "status >= :status"
                  --expression-attribute-values '{":status":{"S":"incomplete"}}'
                  --no-cli-pager
"""
args = [
  # Allow $AWS_REGION to be overridden with a CLI option when calling the task
  {name = "AWS_REGION", options = ["--region", "-r"], default = "${AWS_REGION}"}
]

Run your tasks via the CLI

$ poe test -v tests/unit # extra CLI arguments are appended to the underlying command
Poe => pytest --cov=my_app
...

If you're using poetry or uv, then poe will automatically use CLI tools and libraries from your project's virtualenv without you having to run poetry run / uv run

Poe can also be used as a general purpose task runner.