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 (or poe_tasks.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

✅  Also works fine without poetry

Quick start

1. Install the CLI globally from PyPI using pipx (or via another method):

   pipx install poethepoet
   

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

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

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

Using this feature you can also define global tasks that are not associated with any particular project.