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 via pipx or another method.

pipx install poethepoet

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

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