Poe the Poet
A batteries included task runner that works well with poetry or uv.
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 and task grouping (just run
poewith no arguments) -
✅ Tasks can be composed to run in sequence, in parallel, or as a DAG.
-
✅ Works with
.envfiles -
✅ 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
-
✅ Ships with an official Agent Skill to help AI coding agents use poe effectively
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.48"
- 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.
Contributing
There's plenty to do, come say hi in the discussions or open an issue! 👋
Also check out the CONTRIBUTING guide 🤓
License
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file poethepoet-0.48.0.tar.gz.
File metadata
- Download URL: poethepoet-0.48.0.tar.gz
- Upload date:
- Size: 148.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a06f49d244fadfc2e2e7faa78b54e64a9694727e4ce1d50e08f23cea3ded74f1
|
|
| MD5 |
528481589ed0ce85fc0728d9d6fdc4c5
|
|
| BLAKE2b-256 |
5c9293a4af9511b8c7c647874521d9e6c904266be98067c2ee1eb2e74520d208
|
Provenance
The following attestation bundles were made for poethepoet-0.48.0.tar.gz:
Publisher:
ci.yml on nat-n/poethepoet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
poethepoet-0.48.0.tar.gz -
Subject digest:
a06f49d244fadfc2e2e7faa78b54e64a9694727e4ce1d50e08f23cea3ded74f1 - Sigstore transparency entry: 2083071615
- Sigstore integration time:
-
Permalink:
nat-n/poethepoet@e4d032ce63f6a80cef9b7fc9a956c5f4de04c9b2 -
Branch / Tag:
refs/tags/v0.48.0 - Owner: https://github.com/nat-n
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@e4d032ce63f6a80cef9b7fc9a956c5f4de04c9b2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file poethepoet-0.48.0-py3-none-any.whl.
File metadata
- Download URL: poethepoet-0.48.0-py3-none-any.whl
- Upload date:
- Size: 185.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
98da6096d060f49b8d84034770265863fb7dc92a40233b7694b9d216ac68737d
|
|
| MD5 |
5ed079cd2ae94f95443c69ce65992214
|
|
| BLAKE2b-256 |
598dd7c9455b15f8d2d7ce57e7b71a8ef8d02d9992ae4283c9777120620c9022
|
Provenance
The following attestation bundles were made for poethepoet-0.48.0-py3-none-any.whl:
Publisher:
ci.yml on nat-n/poethepoet
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
poethepoet-0.48.0-py3-none-any.whl -
Subject digest:
98da6096d060f49b8d84034770265863fb7dc92a40233b7694b9d216ac68737d - Sigstore transparency entry: 2083071626
- Sigstore integration time:
-
Permalink:
nat-n/poethepoet@e4d032ce63f6a80cef9b7fc9a956c5f4de04c9b2 -
Branch / Tag:
refs/tags/v0.48.0 - Owner: https://github.com/nat-n
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
ci.yml@e4d032ce63f6a80cef9b7fc9a956c5f4de04c9b2 -
Trigger Event:
push
-
Statement type:
