### Installing Poetry with PowerShell Interpreter

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/shell.rst

This example shows how to execute a PowerShell script to install Poetry. It specifies 'pwsh' as the interpreter, ensuring the script runs in a PowerShell environment.

```toml
[tool.poe.tasks.install-poetry]
shell = """
(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python - 
"""
interpreter = "pwsh"
```

--------------------------------

### Install uv and Poe the Poet

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/tox_replacement_guide.rst

Installs uv using a curl script and Poe the Poet using uv.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Poe the Poet
uv tool install poethepoet
```

--------------------------------

### Install Poetry Plugin Globally

Source: https://github.com/nat-n/poethepoet/blob/main/docs/poetry_plugin.rst

Installs the poethepoet poetry plugin globally using the poetry CLI.

```sh
poetry self add 'poethepoet[poetry_plugin]'
```

--------------------------------

### Install Poe the Poet with uv

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install the Poe the Poet CLI globally using uv. This method ensures the 'poe' executable is accessible from anywhere on your system.

```sh
uv tool install poethepoet
```

--------------------------------

### Install Poe the Poet with Homebrew

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe the Poet using Homebrew by tapping the repository and then installing the formula. This makes the 'poe' executable available globally.

```sh
brew tap nat-n/poethepoet
brew install nat-n/poethepoet/poethepoet
```

--------------------------------

### Example Parallel Task Output

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/parallel.rst

Illustrates the expected output format for parallel tasks when custom prefix configurations are applied, including truncation.

```text
[1:build] first task output line
[2:test] second task output line
[3:deploy_…] third task output line

```

--------------------------------

### Example Command Line Execution for Sequence Task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Illustrates how a command line invocation translates to argument forwarding for a sequence task.

```sh
poe test-all --cov=mypackage -v
```

--------------------------------

### Example Command Line Execution for Script Task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Demonstrates how command line arguments are passed to a script task's function via the `_extra_args` variable.

```sh
poe run-tests tests/unit -x -v
```

--------------------------------

### Private Argument Example

Source: https://github.com/nat-n/poethepoet/blob/main/docs/env_vars.rst

This example demonstrates how to define a private argument for a task. Private arguments, starting with an underscore and containing no uppercase characters, are available during configuration time but not exposed to the task subprocess at runtime.

```toml
[tool.poe.tasks.cook]
script = "kitchen:frying_pan(_food)"
args = [{ name = "_food", default = "eggs" }]
```

--------------------------------

### Example Command Line Execution for Cmd Task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Shows the resulting command string when extra arguments are explicitly managed in a cmd task.

```sh
poe coverage tests/unit -x
```

--------------------------------

### Example Parallel Task Output with Prefixes

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/parallel.rst

Illustrates the default output formatting for parallel tasks, where each line is prefixed with the task name and a color to identify its origin.

```html
<div class="highlight-sh notranslate">
<div class="highlight">
<pre id="codecell5">
<span style="color:red">task_1</span> | task_1 output line 1
<span style="color:green">task_2</span> | task_2 output line 1
<span style="color:yellow">task_3</span> | task_3 output line 1
<span style="color:red">task_1</span> | task_1 output line 2
<span style="color:blue">task_4</span> | task_4 output line 1
<span style="color:yellow">task_3</span> | task_3 output line 2
<span style="color:magenta">task_5</span> | task_5 output line 1
<span style="color:cyan">task_6</span> | task_6 output line 1
</pre>
</div>
</div>
```

--------------------------------

### Example Shell Task with Custom Interpreter

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

An example of a shell task that utilizes the custom 'fish' shell interpreter configured globally. It demonstrates a recursive Fibonacci sequence calculation.

```shell
function fib --argument-names max n0 n1
  if test $max -ge $n0
    echo $n0
    fib $max $n1 (math $n0 + $n1)
  end
end

fib 89 1 1
```

--------------------------------

### Equivalent Shell Execution

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/ref.rst

This shell command demonstrates the equivalent execution of the 'do_specific_things' ref task defined in the TOML example. It shows how the environment variable and arguments are passed.

```sh
poe do_specific_things
```

--------------------------------

### Define Sequence Task with Task References

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/sequence.rst

This example shows how to define a sequence task named 'release' that runs three other tasks ('test', 'build', and '_publish') in order. Tasks prefixed with an underscore are internal and not directly runnable.

```toml
[tool.poe.tasks]
test = "pytest --cov=src"
build = "poetry build"
_publish = "poetry publish"
release = ["test", "build", "_publish"] # run all three tasks in sequence
```

--------------------------------

### Install Poe the Poet with pipx

Source: https://github.com/nat-n/poethepoet/blob/main/README.md

Install Poe the Poet globally using pipx. This is a common method for installing CLI tools.

```sh
pipx install poethepoet
```

--------------------------------

### Run Poe Task from CLI

Source: https://github.com/nat-n/poethepoet/blob/main/README.md

Example of executing a defined Poe task from the command line. Shows how extra arguments are passed to the underlying command.

```sh
$ poe test -v tests/unit # extra CLI arguments are appended to the underlying command
Poe => pytest --cov=my_app
...
```

--------------------------------

### Running a Shell Task with Arguments

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Example of how to run a Poe task that accepts arguments, specifically the 'passby' task with the '--planet' option.

```sh
poe passby --planet mars
```

--------------------------------

### Example of 'clean' task execution

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/cmd.rst

This shows the output when the 'clean' task, defined with glob patterns, is executed using Poe.

```sh
$ poe clean
Poe => rm -rf ./tests/__pycache__ ./docs/__pycache__ ...
```

--------------------------------

### Run Poe as a Poetry Plugin

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/running_guide.rst

Executes Poe tasks when installed as a Poetry plugin (for poetry >= 1.2). Requires installing the plugin and then using the 'poetry poe' command.

```sh
poetry self add poethepoet[poetry_plugin]
poetry poe [options] test [task_args]
```

--------------------------------

### Switch Task with Multiple Values per Case (TOML)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Configures a build task where a single case can match multiple values. This example runs the 'build' command if the platform is either 'linux' or 'darwin'.

```toml
[[tool.poe.tasks.build.switch]]
case = ["linux", "darwin"]
cmd  = "build"

```

--------------------------------

### Invoke Task with Positional Arguments

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Example of how to invoke a task with defined positional arguments on the CLI.

```bash
poe serve --host 0.0.0.0 --port 8001
```

--------------------------------

### Running Cmd Task with Free Arguments

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Example of executing the 'lint' task, specifying the '--target' option and then passing '--fix' as a free argument to the underlying 'ruff check' command.

```sh
poe lint -t tests -- --fix
```

--------------------------------

### Glob Expansion Example

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/cmd.rst

Illustrates glob expansion in 'cmd' tasks. Glob patterns are expanded relative to the task's working directory. The 'empty_glob' option can control behavior when no files match.

```toml
# Example demonstrating glob expansion (no specific code block provided in source, conceptual)
```

--------------------------------

### Enable Bash tab completion for Poe

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe's Bash tab completion scripts. This can be done via direct evaluation in ~/.bashrc or by installing to a file for user or system-wide use.

```bash
# Quick setup - add to ~/.bashrc
eval "$(poe _bash_completion)"

# Or install to a file (requires new shell to take effect):

# User local (recommended)
mkdir -p ~/.local/share/bash-completion/completions
poe _bash_completion > ~/.local/share/bash-completion/completions/poe

# System-wide
poe _bash_completion | sudo tee /etc/bash_completion.d/poe > /dev/null

# Homebrew bash
poe _bash_completion > $(brew --prefix)/etc/bash_completion.d/poe
```

--------------------------------

### Define Poe Tasks in pyproject.toml

Source: https://github.com/nat-n/poethepoet/blob/main/docs/index.rst

Example of defining various task types (command, script, shell) and a task with documentation and named arguments in the pyproject.toml file.

```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'}}'\n                  --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}"}
]
```

--------------------------------

### Install Poe the Poet with pip

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe the Poet using pip. This method assumes your current Python environment is global and makes the 'poe' executable available.

```sh
pip install poethepoet
```

--------------------------------

### Display Help for a Single Task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/help_guide.rst

Use 'poe --help <task_name>' to get detailed information about a specific task, including its description, usage, and arguments. This helps in understanding how to use individual tasks.

```sh
$ poe --help tunnel
```

--------------------------------

### Define Poe Tasks in pyproject.toml

Source: https://github.com/nat-n/poethepoet/blob/main/README.md

Example of defining various task types in the pyproject.toml file. Includes simple commands, script-based tasks, and shell tasks.

```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
```

--------------------------------

### Enable Fish tab completion for Poe

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe's Fish tab completion scripts. This involves placing the completion script in the appropriate directory for Fish shell.

```fish
# Fish
poe _fish_completion > ~/.config/fish/completions/poe.fish

# Homebrew fish
poe _fish_completion > (brew --prefix)/share/fish/vendor_completions.d/poe.fish
```

--------------------------------

### Set Default Executor to 'simple'

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Configure Poe to use the 'simple' executor globally, which runs tasks without specific environment setup.

```toml
[tool.poe]
executor = "simple"
```

--------------------------------

### Enable Powershell tab completion for Poe

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe's Powershell tab completion scripts by adding the output of the completion command to your Powershell profile.

```pwsh
# add to $PROFILE
poe _powershell_completion | out-string | invoke-expression
```

--------------------------------

### Shell Task with Named Arguments

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/shell.rst

This example defines a shell task that accepts named arguments 'NAME' and 'GREETING', providing default values. Argument values are exposed as environment variables within the shell script.

```toml
[tool.poe.tasks.greet]
shell = """
echo "${GREETING} ${NAME}"
echo "How are you?"
"""
args = [
  { name = "NAME", default = "world" },
  { name = "GREETING", default = "Hi" },
]
```

--------------------------------

### Run a Task with Poe CLI

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/running_guide.rst

Executes a defined Poe task using the standalone Poe CLI. Ensure Poe is installed globally or the virtual environment is sourced.

```sh
poe test
```

--------------------------------

### Run Poe as a Poetry Dependency

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/running_guide.rst

Executes Poe tasks when installed as a development dependency with Poetry. Use 'poetry run poe' to execute tasks within the Poetry-managed virtual environment.

```sh
poetry add --group dev poethepoet
poetry run poe [options] test [task_args]
```

--------------------------------

### Display All Configured Tasks Help

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/help_guide.rst

Run 'poe --help' to see a list of all tasks, their descriptions, and global options. This is useful for understanding available commands.

```sh
$ poe --help
```

--------------------------------

### Background SSH Tunnels with Shell Tasks

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/shell.rst

This snippet demonstrates opening multiple SSH tunnels in the background using shell task syntax. It requires defining two tasks: one to start the tunnels and another to stop them.

```toml
[tool.poe.tasks.pfwd]
shell = """
  ssh -N -L 0.0.0.0:8080:$STAGING:8080 $STAGING &
  ssh -N -L 0.0.0.0:5432:$STAGINGDB:5432 $STAGINGDB &
"

[tool.poe.tasks.pfwdstop]
shell = """kill $(pgrep -f \"ssh -N -L .*:(8080|5432)\")"""
```

--------------------------------

### Enable Zsh tab completion for Poe

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Install Poe's Zsh tab completion scripts. This can be done for oh-my-zsh or a standard Zsh setup to enhance shell usability.

```zsh
# oh-my-zsh
mkdir -p ~/.oh-my-zsh/completions
poe _zsh_completion > ~/.oh-my-zsh/completions/_poe

# without oh-my-zsh
mkdir -p ~/.zfunc/
poe _zsh_completion > ~/.zfunc/_poe
```

--------------------------------

### Running a Basic Expr Task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/expr.rst

Shows how to execute the 'trivial-example' task and the expected output, which is the evaluated result of the expression.

```bash
$ poe trivial-example
Poe => 1 + 1
2
```

--------------------------------

### Run a Package's __main__ Module

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/script.rst

Execute a package's __main__.py module as a script task. Command-line arguments are forwarded.

```toml
[tool.poe.tasks]
fetch-assets.script = "http.server"
```

--------------------------------

### Define Tasks in an Included TOML File

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/include_guide.rst

Example of tasks defined in an external TOML file that can be included by Poe.

```toml
[tool.poe.tasks.build-image]
cmd = "docker build"
```

--------------------------------

### Specify Multiple Environment Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Configure a task to load environment variables from multiple specified envfiles. Files are loaded in the order they appear in the list.

```toml
serve.envfile = [".env", "local.env"]
```

--------------------------------

### Configure Optional Environment Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Specify environment files that are optional, suppressing warnings if they are not found.

```toml
[tool.poe]
envfile.optional = ".env"
```

--------------------------------

### Change Default Shell Interpreter

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Overrides the default shell interpreter for all shell tasks. This example sets the default to 'fish' shell.

```toml
tool.poe.shell_interpreter = "fish"
```

--------------------------------

### Configure Expected and Optional Environment Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Manage both required and optional environment files for Poe tasks.

```toml
[tool.poe.envfile]
expected = ["shared.env"]
optional = ["local.env"]
```

--------------------------------

### Define Arguments with Options and Defaults

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Configure arguments with specific CLI options (like short and long flags) and default values using an array of tables in the 'args' option.

```toml
[[tool.poe.tasks.serve.args]]
name = "host"
options = ["-h", "--host"]
help = "The host on which to expose the service"
default = "localhost"

[[tool.poe.tasks.serve.args]]
name = "port"
options = ["-p", "--port"]
help = "The port on which to expose the service"
default = "8000"
```

--------------------------------

### Run PoeThePoet as a Library

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/library_guide.rst

This script demonstrates how to instantiate and run PoeThePoet programmatically, passing command-line arguments to it. It replicates the core functionality of the `poe` standalone CLI.

```python
import sys

from poethepoet.app import PoeThePoet


if __name__ == "__main__":
    app = PoeThePoet()
    result = app(cli_args=sys.argv[1:])
    if result:
        sys.exit(result)
```

--------------------------------

### Configure UV Executor with Options

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Set the default executor to 'uv' and configure task-specific options like 'isolated', 'python', and 'with' for dependency management.

```toml
[tool.poe.executor]
type = "uv"

[tool.poe.tasks.test-py311]
cmd = "pytest tests"
executor = {isolated = true, python = "3.11", with = ["pytest"]}

[tool.poe.tasks.test-py312]
cmd = "pytest tests"
```

--------------------------------

### Console Help Output with Choices

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Demonstrates how argument choices are displayed in the help output for a Poe task.

```console
$ poe --help share

    Description:
      Run Share some personal information

    Usage:
      poe [global options] check [named arguments] -- [free arguments]

    Named arguments:
      flavor               Favorite ice cream [choices: 'chocolate', 'pistachio', 'vanilla']
```

--------------------------------

### Executing Expr Task with Arguments and Environment Variables

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/expr.rst

Demonstrates running the 'venv-active' task and its output, showing how the expression evaluates based on the provided argument and environment variable.

```sh
$ poe venv-active poethepoet-LCpCQf8S-py3.10
Poe => (
  f'{target_venv} is active' if '${VIRTUAL_ENV}'.endswith(target_venv) else f'{target_venv} is not active'
)
poethepoet-LCpCQf8S-py3.10 is not active
```

--------------------------------

### Include Multiple Task Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/include_guide.rst

Include tasks from multiple files by providing a list of paths. Files are loaded in the order specified, and existing tasks are ignored.

```toml
[tool.poe]
include = ["modules/acme_common/shared_tasks.toml", "generated_tasks.json"]
```

--------------------------------

### Invoke Task with Private Positional Argument

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Example of invoking a task with a private positional argument. The leading underscore is stripped from the argument name for CLI usage.

```bash
poe cook --food eggs
```

--------------------------------

### Specify a different executor for included script

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Customize the executor used to find and execute the referenced Python package. This example uses a specific virtualenv location.

```toml
[[tool.poe.include_script]]
script   = "mypkg:get_tasks"
executor = { type = "virtualenv", location = "../parent.venv" }
```

--------------------------------

### Call Standard Library Function

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/script.rst

Use Python's standard library functions, like `os.makedirs`, for cross-platform task execution.

```toml
[tool.poe.tasks.build]
script = "os:makedirs('build/assets', exist_ok=True)"
```

--------------------------------

### Run Poe with uv

Source: https://github.com/nat-n/poethepoet/blob/main/docs/installation.rst

Execute Poe tasks within your project using uv's run command after adding Poe as a dev dependency.

```sh
uv run poe
```

--------------------------------

### Define a Sequence Task (Implicit)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/composition_guide.rst

Compose tasks into a new task that runs them in order by declaring a sequence task. This example uses implicit TOML task definition.

```toml
[tool.poe.tasks]

_publish = "poetry publish"
release = [
  { cmd = "pytest --cov=src" },
  { script = "devtasks:build" },
  { ref = "_publish" },
]
```

--------------------------------

### Define a TaskCollection with a cmd task

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Demonstrates how to create a TaskCollection and add a simple command task with optional tags. This is the recommended way to manage tasks in Python.

```python
from poethepoet_tasks import TaskCollection

tasks = TaskCollection()

# Define a simple cmd task
tasks.add(
    task_name="test",
    task_config={
        "help": "Run project tests",
        "cmd": "pytest tests",
    },
    tags=["pytest"], # tags are optional and allow consumers to select only the desired tasks
)
```

--------------------------------

### Define tasks function returning config structure

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Example of a Python function that generates tasks configuration. The returned structure is similar to what is supported when loading tasks from another file.

```python
def generate_tasks():
  return {
    "tasks": {
      "test": "pytest",
      "build-proto": {
        "cmd": """
          protoc --proto_path=schemas --python_out=src/generated schemas/messages.proto
        """,
        "help": "Generate protobuf classes"
      },
      "build": {
        "sequence": [
          "build-proto",
          "test",
          { "cmd": "poetry build" },
        ],
        "help": "Build that code"
      }
    }
  }
```

--------------------------------

### Switch Task with Default Pass on No Match (TOML)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Sets up a build task that will pass even if no case matches the control task's output. This is useful for optional tasks or when a default action is not strictly required.

```toml
[tool.poe.tasks.build-on-windows]
control.expr = "sys.platform"
default = "pass"

  [[tool.poe.tasks.build-on-windows.switch]]
  case = "win32"
  cmd  = "build"

```

--------------------------------

### Default Plugin Command Prefix

Source: https://github.com/nat-n/poethepoet/blob/main/docs/poetry_plugin.rst

Shows the default usage of the poetry plugin where 'poe' is the command prefix.

```sh
poetry poe [task_name] [task_args]
```

--------------------------------

### Configure Virtualenv Executor with Git Directory Template

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Configures the virtualenv executor to use a location relative to the Git repository root using a special environment variable. This is useful in monorepo setups.

```toml
[tool.poe.executor]
type = "virtualenv"
location = "${POE_GIT_DIR}/myvenv"
```

--------------------------------

### Add poethepoet-tasks as a dev dependency with uv

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Add the 'poethepoet-tasks' package as a development dependency using uv.

```sh
uv add --dev poethepoet-tasks
```

--------------------------------

### Include Files Relative to Git Repository Root

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/include_guide.rst

Use special variables like POE_GIT_DIR or POE_GIT_ROOT to specify include paths relative to the root of the git repository, which is useful in monorepo setups.

```toml
[tool.poe]
include = "${POE_GIT_DIR}/tasks.toml"
```

--------------------------------

### Load Environment Variables from an Env File

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Specify a file to load environment variables for all tasks. Supports bash-like syntax.

```bash
STAGE=dev
PASSWORD='!@#$%^&*('
```

```toml
[tool.poe]
envfile = ".env"
```

--------------------------------

### Loading Environment Variables from an Env File

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Specify one or more environment files to be loaded before a task runs. These files use bash-like syntax for defining variables.

```bash
# .env
STAGE=dev
PASSWORD='!@#$%^&*('
```

```toml
[tool.poe.tasks]
serve.script  = "myapp:run"
serve.envfile = ".env"
```

--------------------------------

### Setting Task Specific Environment Variables

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Define environment variables for a specific task using the 'env' option. Supports deep keys for convenience. Private variables starting with '_' are not exposed to the subprocess but can be used for configuration.

```toml
[tool.poe.tasks.serve]
script = "myapp:run"
env = { PORT = "9001" }
```

```toml
[tool.poe.tasks.run]
ref = "_serve"
args = ["_favorite_number"]

[tool.poe.tasks._serve]
help = "This indirection is pointless but illustrates the point"
script = "myapp:run"
env = { PORT = "${_favorite_number}" }
```

--------------------------------

### Optional and Expected Environment Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Define environment files as either optional or expected for a task. Optional files are loaded after expected files, and the last file in the sequence with a conflicting variable wins.

```toml
[tool.poe.tasks.serve.envfile]
optional = ["local.env"]
expected = ["base.env"]
```

--------------------------------

### Load Multiple Environment Files

Source: https://github.com/nat-n/poethepoet/blob/main/docs/global_options.rst

Configure Poe to load environment variables from a list of specified files in order.

```toml
[tool.poe]
envfile = ["standard.env", "local.env"]
```

--------------------------------

### Basic tox.ini configuration

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/tox_replacement_guide.rst

A typical tox.ini file defining test environments and commands.

```ini
[tox]
envlist = py310,py311,py312,py313

[testenv]
deps = pytest
       pytest-cov
commands = pytest tests --cov=mypackage
```

--------------------------------

### Generate Bash Completion for Global Tasks

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/global_tasks.rst

Generates a bash completion script for a global Poe alias. This is necessary for bash users to enable tab completion for global tasks. Ensure Poe the Poet is installed globally and the alias and task path are correctly specified.

```bash
# System bash
poe _bash_completion edgar ~/.poethepoet > /etc/bash_completion.d/edgar.bash-completion
```

```bash
# Homebrew bash
poe _bash_completion edgar ~/.poethepoet > $(brew --prefix)/etc/bash_completion.d/edgar.bash-completion
```

--------------------------------

### Basic Switch Task with Platform Detection (TOML)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Defines a build task that selects a subtask based on the operating system platform. It runs a Windows-specific command if 'win32' is detected, otherwise falls back to a POSIX command.

```toml
[tool.poe.tasks.build]
control.expr = "sys.platform"

  [[tool.poe.tasks.build.switch]]
  case = "win32"
  cmd  = "windows_build"

  [[tool.poe.tasks.build.switch]]
  cmd  = "posix_build"

```

--------------------------------

### Redirect Task Standard Output to File

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Configure a task to capture its standard output and write it to a specified file. Relative paths are resolved from the project root.

```toml
[tool.poe.tasks.serve]
cmd = "gunicorn ./my_app:run"
capture_stdout = "gunicorn_log.txt"
```

--------------------------------

### Display Task List with Groups

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/help_guide.rst

Running 'poe' without arguments shows ungrouped tasks first, followed by tasks organized into groups, sorted alphabetically by group name. This provides a structured overview of available tasks.

```sh
Configured tasks:
  <span style="color:#56B6C2">test</span>           Run the tests

<span style="color:#98C379">Application Serving</span>
  <span style="color:#56B6C2">dev</span>            Run the app in debug mode
  <span style="color:#56B6C2">prod</span>           Run the app in production mode

<span style="color:#98C379">Testing &amp; Quality</span>
  <span style="color:#56B6C2">unit</span>           Run the test suite
```

--------------------------------

### Combine Sequence and Parallel Tasks

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/composition_guide.rst

Demonstrates combining sequence and parallel task execution. By default, a list within a sequence is interpreted as a parallel task.

```toml
[tool.poe.tasks.check-code]
sequence = [
  ["mypy", "pylint"], # First these two tasks run in parallel
  "pytest"            # then this task runs after both complete
]
```

--------------------------------

### Switch Task Based on Named Argument (TOML)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Sets up an 'icecream' task that selects a subtask based on the 'flavor' named argument. It defines specific commands for 'chocolate' and 'strawberry', with a default for 'vanilla'.

```toml
[tool.poe.tasks.icecream]
control.expr = "flavor"
args = ["flavor"]

  [[tool.poe.tasks.icecream.switch]]
  case = "chocolate"
  cmd  = "make_chocolate_icecream"

  [[tool.poe.tasks.icecream.switch]]
  case = "strawberry"
  cmd  = "make_strawberry_icecream"

  [[tool.poe.tasks.icecream.switch]]
  cmd  = "make_vanilla_icecream"

```

--------------------------------

### Referencing Environment Variables

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/cmd.rst

Demonstrates how to reference environment variables within a command. Whitespace in variables causes word breaks, and glob patterns are evaluated after expansion unless quoted.

```toml
[tool.poe.tasks]
greet = "echo Hello ${USER}"
```

--------------------------------

### Combine Parallel and Sequence Tasks

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/composition_guide.rst

Demonstrates combining parallel and sequence task execution. A list within a parallel task is interpreted as a sequence task.

```toml
[tool.poe.tasks.check-code]
parallel = [
  "mypy",
  "pylint",
  [ # These tasks will run in sequence, concurrently with the others
    "build-deps",
    "pytest"
  ]
]
```

--------------------------------

### Switch Task Based on Environment Variable Execution (Shell)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Demonstrates how to execute the 'check_number' task with different environment variables to show the even and odd output.

```sh
$ BEST_NUMBER=12 poe check_number
Poe <= int(${BEST_NUMBER}) % 2
Poe => f'{${BEST_NUMBER}} is even')
12 is even

$ BEST_NUMBER=17 poe check_number
Poe <= int(${BEST_NUMBER}) % 2
Poe => f'{${BEST_NUMBER}} is odd'
17 is odd

```

--------------------------------

### Switch Task with Named Argument Execution (Shell)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/switch.rst

Shows how to invoke the 'icecream' task with a specific flavor argument to trigger the corresponding subtask execution.

```sh
$ poe icecream --flavor chocolate
Poe <= flavor
Poe => make_chocolate_icecream
...

```

--------------------------------

### Runtime Configuration of UV Executor Options

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Override or add executor configurations at runtime using the `--executor-opt` CLI option. This allows for flexible execution of tasks with different settings without modifying the Poe configuration file.

```bash
poe --executor uv --executor-opt with=pytest --executor-opt isolated --executor-opt with=pytest-cov --executor-opt python=3.12 test --cov my_package
```

--------------------------------

### Multiple Values for Positional Argument

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Shows how to configure a positional argument to accept multiple values, which are then passed as whitespace-separated values in cmd tasks.

```toml
[tool.poe.tasks.save]
cmd  = "echo ${FILE_PATHS}"
args = [{ name = "FILE_PATHS", positional = true, multiple = true }]
```

--------------------------------

### Define Task Help Text in TOML

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/help_guide.rst

Add 'help' strings to task definitions in pyproject.toml. This text is displayed when 'poe' is run without arguments.

```toml
[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_host:8080 $prod_host &"
args   = [
  {name = "prod_host", help = "Hostname of the production server", default = "myapp.com"}
]
```

--------------------------------

### Sequence Task Argument Forwarding

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Illustrates how arguments defined for a sequence task can be passed to its subtasks, like 'build' and 'run_tests'. The '_target' argument is used in both.

```toml
[tool.poe.tasks.build]
script = "util:build_app"
args = [{ name = "target", positional = true }]

[tool.poe.tasks.check]
sequence = ["build ${_target}", { script = "util:run_tests(_target)" }]
args = ["_target"]
```

--------------------------------

### Define Arguments using Subtable Configuration

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Configure arguments using a subtable of tables structure, providing the same functionality as the array of tables approach but with a different TOML syntax.

```toml
[tool.poe.tasks.serve.args.host]
options = ["-h", "--host"]
help = "The host on which to expose the service"
default = "localhost"

[tool.poe.tasks.serve.args.port]
options = ["-p", "--port"]
help = "The port on which to expose the service"
default = "8000"
```

--------------------------------

### Define Arguments with Defaults

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Configure arguments with default values using an array of inline tables in the 'args' option. This allows arguments to be optional on the CLI.

```toml
[tool.poe.tasks.serve]
cmd = "myapp:run"
args = [
  { name = "host", default = "localhost" },
  { name = "port", default = "9000" }
]
```

--------------------------------

### Default Environment Variable for Argument

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Demonstrates how to set a default value for an argument using an environment variable. The precedence is command line > environment variable > task default.

```toml
[tool.poe.tasks.deploy]
cmd = "..."
env.AWS_REGION.default = "eu-central-1"

[[tool.poe.tasks.deploy.args]]
name    = "region"
help    = "The region to deploy to"
default = "${AWS_REGION}"
```

--------------------------------

### Run Poe Quality Checks

Source: https://github.com/nat-n/poethepoet/blob/main/CLAUDE.md

Execute all quality checks including style, types, linting, and tests. This command can take a significant amount of time.

```bash
poe check             # run all quality checks (style, types, lint, tests) - this takes a while.
poe test              # run full test suite
poe test-quick        # skip slow/flaky tests
poe format            # auto-format code (ruff + black)
poe lint              # ruff linting only
poe types             # mypy type checking
```

--------------------------------

### Cmd Task with Named and Free Arguments

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Defines a 'lint' command task with a named argument 'target_dir' and shows how to pass additional free arguments using '--'.

```toml
[tool.poe.tasks.lint]
cmd  = "ruff check ${target_dir}"
args = { target_dir = { options = ["--target", "-t"], default = "." }}
```

--------------------------------

### Sequence Task with Inline Task Definitions (Array of Inline Tables)

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/sequence.rst

A more succinct syntax for defining a 'release' sequence task using an array of inline tables and strings. This is useful for simpler sequences.

```toml
[tool.poe.tasks]

release = [
  { cmd = "pytest --cov=src" },
  { script = "devtasks:build" },
  "_publish"
]
```

--------------------------------

### Include tasks from a Python package

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Load tasks by referencing a function from a Python package. The package must be accessible to the executor.

```toml
[tool.poe]
include_script = "mypkg:get_tasks"
```

--------------------------------

### Constraining Argument Choices

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/args_guide.rst

Illustrates how to restrict an argument to a predefined set of choices, which are also displayed in the task's help output.

```toml
[tool.poe.tasks.share]
help = "Share some personal information"
cmd = "echo \"My favorite ice cream is ${flavor}\""
[[tool.poe.tasks.share.args]]
name = "flavor"
help = "Favorite ice cream"
```

--------------------------------

### Remove pyc files and __pycache__ directories with empty_glob

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/cmd.rst

This snippet demonstrates using glob patterns to remove all .pyc files and __pycache__ directories. The `empty_glob` option set to `null` ensures the command succeeds even if no files match the patterns.

```toml
[tool.poe.tasks.clean]
cmd = """
rm -rf ./**/*.pyc
       ./**/__pycache__    # this will match all __pycache__ dirs in the project
"""
empty_glob = "null"
```

--------------------------------

### Include multiple tasks from different packages

Source: https://github.com/nat-n/poethepoet/blob/main/docs/guides/packaged_tasks.rst

Load tasks from multiple Python packages or modules by providing a list of references.

```toml
[tool.poe]
include_script = ["mypkg:get_tasks", "something.else:more_tasks"]
```

--------------------------------

### Configure UV Executor with Task-Level Dependencies

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Specify task-level dependencies using the `with` option, which are not added to the project's main dependencies. This is useful for tasks that require specific packages only during their execution.

```toml
[tool.poe.tasks.test]
help     = "Run the tests"
cmd      = "pytest"
executor = {type = "uv", with = ["pytest"], isolated = true}
```

--------------------------------

### Set Task Working Directory

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Configure a task to run in a specific working directory other than the project root. Relative paths are resolved from the project root.

```toml
[tool.poe.tasks.build-client]
cmd = "npx ts-node -T ./build.ts"
cwd = "./client"
```

--------------------------------

### View Poe Documentation via Plugin

Source: https://github.com/nat-n/poethepoet/blob/main/docs/poetry_plugin.rst

Invokes the poe documentation view through the poetry plugin.

```sh
poetry poe
```

--------------------------------

### Configure UV Executor with Python Versions

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Define tasks to run with specific Python versions using the uv executor. This allows for testing against multiple Python environments.

```toml
[tool.poe]
executor = "uv"

[tool.poe.tasks.test-py311]
help     = "An alias for the test task that runs with python 3.11"
cmd      = "pytest"
executor = {isolated = true, python = "3.11"}

[tool.poe.tasks.test-py312]
help     = "An alias for the test task that runs with python 3.12"
cmd      = "pytest"
executor = {isolated = true, python = "3.12"}

[tool.poe.tasks.test-matrix]
help     = "Run tests for all python versions"
sequence = ["test-py311", "test-py312"]
```

--------------------------------

### Define a command task with options

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/index.rst

Tasks can be defined as sub-tables to specify task type and configuration. The 'cmd' key identifies a command task.

```toml
[tool.poe.tasks.test-quick]
help = "Run tests excluding those makes as slow."
cmd  = "pytest -m \"not slow\"" # here the cmd key identifies the task type and content
```

--------------------------------

### Configure Task to Use `exec` Instead of Subprocess

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/options.rst

Define tasks that execute within the same process using the `use_exec = true` option. Note that tasks configured this way cannot be referenced by other tasks and do not work on Windows.

```toml
[tool.poe.tasks.serve]
cmd      = "gunicorn ./my_app:run"
use_exec = true
```

--------------------------------

### Continue on Subtask Failure (ignore_fail = "return_non_zero")

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/parallel.rst

Configure a parallel task to run all subtasks to completion but return a non-zero exit code if any subtask fails. This ensures all tasks are attempted while still signaling failure.

```toml
[tool.poe.tasks]
attempts.parallel = ["task1", "task2", "task3"]
attempts.ignore_fail = "return_non_zero"
```

--------------------------------

### Configure Custom Poetry Command Prefix

Source: https://github.com/nat-n/poethepoet/blob/main/docs/poetry_plugin.rst

Sets a custom command prefix for poe tasks within poetry by modifying pyproject.toml.

```toml
[tool.poe]
poetry_command = ""
```

--------------------------------

### Configure Poetry Command Hooks

Source: https://github.com/nat-n/poethepoet/blob/main/docs/poetry_plugin.rst

Configures tasks to run before or after specific poetry commands using the poetry_hooks option in pyproject.toml.

```toml
[tool.poe.poetry_hooks]
pre_build  = "prep-assets --verbosity=5"
post_build = "archive-build"
```

```toml
[tool.poe.tasks.prep-assets]
script = "scripts:prepare_assets"
help   = "Optimise static assets for inclusion in the build"
```

```toml
[tool.poe.tasks.archive-build]
script = "scripts:archive_build"
help   = "Upload the latest build version to the archive server"
```

--------------------------------

### Execute Script Task with Dry Run

Source: https://github.com/nat-n/poethepoet/blob/main/docs/tasks/task_types/script.rst

Demonstrates how Poe handles the --dry-run option for script tasks, simulating execution without actual changes.

```bash
poe -q create-secret
```