Poe the Poet Documentation#

Poe the Poet is a batteries included task runner that works well with poetry.

It provides a simple way to define project tasks within your pyproject.toml, and either a standalone CLI or a poetry plugin to run them using your project’s virtual environment.

“Simple things should be simple, complex things should be possible.” – Alan Kay

Top features#

✅ Straight forward declaration of project tasks in your pyproject.toml

✅ Tasks are run in poetry’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 define 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

Quick start#

Install the CLI globally from PyPI using pipx (or via another method):
```
pipx install poethepoet
```

Add a section for poe tasks to 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

Click here for a real example.

Run one of your tasks using the CLI
```
poe test -v
```
The extra argument is appended to the task command.

Hint

If you’re using poetry, then poe will automatically use the poetry managed virtualenv to find executables and python libraries, without needing to use poetry run or poetry shell.

Usage without poetry#

Poe the Poet was originally intended as the missing task runner for poetry. But it works just as well with any other kind of virtualenv, or simply as a general purpose way to define handy tasks for use within a certain directory structure! This behaviour is configurable via the tool.poe.executor global option.

By default poe will run tasks in the poetry managed virtual environment, if the pyproject.toml contains a tool.poetry section. If it doesn’t then poe looks for a virtualenv to use at ./.venv or ./venv relative to the pyproject.toml.

If no virtualenv is found then poe will run tasks without any special environment management.

Run poe from anywhere#

By default poe will detect when you’re inside a project with a pyproject.toml in the root. However if you want to run it from elsewhere then that is supported by using the --root option to specify an alternate location for the toml file. The task will run with the given location as the current working directory.

In all cases the path to project root (where the pyproject.toml resides) will be available as $POE_ROOT within the command line and process. The variable $POE_PWD contains the original working directory from which poe was run.