0.48.0

Enhancements

• Add uses_env task option for loading variables from another task's output like an env file by @nat-n in #407

Full Changelog: v0.47.1...v0.48.0

0.47.1

Fixes

• Restore default value propagation for absent multiple positional args by @nat-n in #409

Full Changelog: v0.47.0...v0.47.1

0.47.0

Enhancements

• Add buffer output_mode for parallel tasks by @nat-n in #400
• Generate official JSON Schema for poe section in pyproject based on PoeOptions and improve some validation edge cases by @nat-n in #392 #389 #398
• Support declared args on script tasks targeting modules by @nat-n in #396
• Respect the FORCE_COLOR environment variable by @nat-n in #403

Fixes

• Executor config validation now rejects unknown keys by @nat-n in #391
• Support src-layout python path resolution for script, expr, and include_script by @nat-n in #397
• Fully support all three CLI styles for multi-value args by @nat-n in #402

AI Agent Skill 🤖

• The poethepoet skill is now documented and ready for use @nat-n in #404
• Improve coverage of expr/switch config semantics and edge cases by @nat-n in #401

Install the skill via one of the following methods:

1. Via a built in poe task (similar to how shell completions are installed):

poe _install_skill                          # auto-detects .claude/.codex/.pi/.agents and prompts
poe _install_skill ~/.claude/skills         # explicit path (substitute your agent's dir)
poe _install_skill <skills-dir> --upgrade   # non-interactive upgrade (skips if same/newer)

2. From github via npx skills

npx skills add https://github.com/nat-n/poethepoet/tree/v0.46.0/poethepoet/skills/poethepoet

Full Changelog: v0.46.0...v0.47.0

0.46.0

Enhancements

• Experimental Claude Code skill and bump-version task by @nat-n in #387
• Use AST parser for all templating to support :- and :+ param expansion operators everywhere by @nat-n in #386
• Add support for environment variable parameter expansion within env files @nat-n in #386

Fixes

• Make uv and poetry executors check for bat files to handle shutdown quirks on windows by @nat-n in #385
• Strip underscore prefix in documentation for private positional args by @nat-n in #383
• Use AST for $POE_EXTRA_ARGS detection and cache parsed content by @nat-n in #388

Experimental agent skill

This release ships an experimental agent skill that gives AI coding agents contextual knowledge of poe's task API when working in projects that use it. It works with any agent that supports the skills convention and aims to improve agent abilities when it comes to leveraging and authoring poe tasks.

Please try it out and provide feedback!

Two install methods:

1. Via a built in poe task (similar to how shell completions are installed):

poe _install_skill                          # auto-detects .claude/.codex/.pi/.agents and prompts
poe _install_skill ~/.claude/skills         # explicit path (substitute your agent's dir)
poe _install_skill <skills-dir> --upgrade   # non-interactive upgrade (skips if same/newer)

2. From github via npx skills

npx skills add https://github.com/nat-n/poethepoet/tree/v0.46.0/poethepoet/skills/poethepoet

Full Changelog: v0.45.0...v0.46.0

0.45.0

Enhancements

• Add support for forwarding free arguments via $POE_EXTRA_ARGS by @timrid in #380

Fixes

• Handle cancelled tasks correctly by @timrid in #378
• Preserve quotes in :+/:- operator arguments (#333) by @nat-n in #377
• Handle ctrl+c attempt on windows if running bat/cmd scripts by @NSPC911 in #382

New Contributors

• @timrid made their first contribution in #378

Full Changelog: v0.44.0...v0.45.0

0.44.0

Enhancements

• Add support for recursive include #317 by @nat-n in #372

Breaking changes**

• Transitive includes are now loaded by default. Previously, if an included config file contained its own include entries, those second-order includes were silently ignored. They are now followed recursively using depth-first loading. This may cause previously ignored config files to be loaded, potentially introducing new tasks or environment variables. To preserve the old behavior for a specific include, set recursive = false on that include entry. See the include guide for details.

Full Changelog: v0.43.0...v0.44.0

0.43.0

Enhancements

• Add task groups for grouping tasks under a heading in help output by @brolewis in #354
• Treat false boolean args as unset env vars and add private vars by @kzrnm in #359

Breaking changes

This release includes a refactor of how task variables are managed, improving boolean arg semantics and introducing private
variables. These changes may affect a small number of existing configurations:

• Boolean args now produce unset env vars when false. Previously false mapped to the string "False"; now the env var is removed entirely. This gives consistent falsy behavior across shells and parameter expansion operators (:-, :+). Tasks checking for the literal string "False" or using os.environ["flag"] will need updating.

• Private env vars are filtered from subprocesses. Variables starting with _ and containing no uppercase characters (e.g. _secret) are now treated as private — available for config-time interpolation but excluded from the task subprocess environment. This is unlikely to affect existing configurations, but any task that relies on a subprocess reading a _lowercase env var will need to rename it.

• Private arg option names strip leading underscores. An arg named _flag with no explicit options now generates --flag instead of --_flag. A new validation rejects duplicate CLI options across args.

See the migration guide for details and recommended fixes.

New Contributors

• @brolewis made their first contribution in #354

Full Changelog: v0.42.1...v0.43.0

0.42.1

Enhancements

• Add exact option for uv executor by @charlesbmi in #365

Completion script fixes

• Isolate zsh completion task options from global options by @nat-n in #364
• Fix completion script edge case handling by @nat-n in #366

Important

You must follow the instructions to (re)install the completion script for your preferred shell environment to benefit from the completion script fixes

New Contributors

• @charlesbmi made their first contribution in #365

Full Changelog: v0.42.0...v0.42.1

0.42.0

Enhancements

• Better zsh completion caaching with max hits per cache and proper TTL before refresh by @nat-n in #360
• Officially Support Python 3.14 by @gruebel in #362
• Add completion script for PowerShell by @NSPC911 in #358

Important

You must follow the instructions to (re)install the completion script for your preferred shell environment to benefit from the enhancements for zsh or PowerShell

New Contributors

• @gruebel made their first contribution in #362
• @NSPC911 made their first contribution in #358

Full Changelog: v0.41.0...v0.42.0

0.41.0

Enhancements

• Full shell completions for global and task arguments in zsh and bash by @nat-n in #355

Full Changelog: v0.40.0...v0.41.0

Important

You must follow the instructions to (re)install the completion script for your preferred shell environment to benefit from the revamped tab completion covering task arguments.