Documenting tasks

You can add help text to your tasks by adding the help option to the task definition, like so:

[tool.poe.tasks.test]
help = "Run the test suite"
cmd = "pytest --cov=poethepoet"

[tool.poe.tasks.serve]
help = "Run the app in debug mode"
script = "my_app.service:run(debug=True)"

[tool.poe.tasks.tunnel]
help = "Create an SSH tunnel to the production server"
shell = "ssh -N -L 0.0.0.0:8080:$PROD:8080 $PROD &"

This help text will be displayed alongside the task name in the list of configured tasks when poe is run without specifying a task.

$ poe --help
Poe the Poet - A task runner that works well with poetry.
version 0.19.0

USAGE
  poe [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi] task [task arguments]

GLOBAL OPTIONS
  -h, --help     Show this help page and exit
  --version      Print the version and exit
  -v, --verbose  Increase command output (repeatable)
  -q, --quiet    Decrease command output (repeatable)
  -d, --dry-run  Print the task contents but don't actually run it
  --root PATH    Specify where to find the pyproject.toml
  --ansi         Force enable ANSI output
  --no-ansi      Force disable ANSI output

CONFIGURED TASKS
  test           Run the test suite
  serve          Run the app in debug mode
  tunnel         Create an SSH tunnel to the production server