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 global options too for zsh)

• ✅ 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 into sequences or DAGs

• ✅ 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

1. 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.35"

2. 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}"}
]

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

Contributing

There's plenty to do, come say hi in the discussions or open an issue! 👋

Also check out the CONTRIBUTING guide 🤓

License

MIT