tessl/pypi-poethepoet

A batteries included task runner that works well with poetry and uv

—

Pending

Overview

Eval results

Files

CLI Usage

Name: tessl/pypi-poethepoet
Author: tessl

Command-line interface providing task execution, help system, shell completion, and comprehensive argument handling for interactive and scripted usage.

Capabilities

Main CLI Entry Point

The primary command-line interface accessed through the poe command after installation.

def main() -> None:
    """
    Main CLI entry point function.
    
    Processes sys.argv arguments and executes poethepoet application.
    Handles builtin completion tasks and regular task execution.
    Exits with appropriate status code.
    """

Command Syntax

poe [global_options] [task_name] [task_arguments]

Global Options

# Global CLI arguments available for all commands

# Help and Information
-h, --help [TASK]     # Show help for command or specific task
--version             # Show version information

# Verbosity Control  
-v, --verbose         # Increase output (repeatable: -v, -vv, -vvv)
-q, --quiet           # Decrease output (repeatable: -q, -qq, -qqq)

# Execution Control
-d, --dry-run         # Print the task contents but don't actually run it
-C, --directory PATH  # Specify where to find the pyproject.toml

# Environment Control
-e, --executor EXECUTOR  # Override executor type (poetry, uv, simple, virtualenv)

# Output Control
--ansi               # Force enable ANSI colors
--no-ansi            # Force disable ANSI colors

Task Execution

Basic Task Execution

# Run a task defined in pyproject.toml
poe test

# Run with arguments passed to the task
poe serve --port 8080

# Run with verbose output
poe -v build

# Dry run to see what would be executed
poe -d deploy

Advanced Execution

# Change directory before running
poe -C /path/to/project test

# Override executor
poe -e simple test

# Multiple verbosity levels
poe -vv debug_task    # Very verbose
poe -q background_job # Quiet mode

# Disable colors for scripting
poe --no-ansi test | tee output.log

Help System

General Help

# Show available tasks and general help
poe

# Show help for specific task
poe -h test
poe --help serve

# Show version information
poe --version

Task Information Display

When running poe without arguments, displays:

Available tasks with descriptions
Global options
Configuration file location
Environment information

Shell Completion

Poethepoet provides shell completion for task names and global options.

# Builtin completion functions (internal use)
def _run_builtin_task(
    task_name: str, 
    second_arg: str = "", 
    third_arg: str = ""
) -> bool:
    """
    Run builtin completion tasks.
    
    Args:
        task_name: Completion task name (_list_tasks, _zsh_completion, etc.)
        second_arg: Config path or alias name
        third_arg: Additional config path for bash completion
        
    Returns:
        True if task was handled
    """

def _list_tasks(target_path: Optional[str] = None) -> None:
    """
    List available tasks for shell completion.
    
    Args:
        target_path: Path to search for configuration
    """

Bash Completion Setup

# Generate bash completion script
poe _bash_completion poe

# Install completion (add to ~/.bashrc)
eval "$(poe _bash_completion poe)"

Zsh Completion Setup

# Generate zsh completion script  
poe _zsh_completion poe

# Install completion (add to ~/.zshrc)
eval "$(poe _zsh_completion poe)"

Fish Completion Setup

# Generate fish completion script
poe _fish_completion poe > ~/.config/fish/completions/poe.fish

Environment Integration

Poetry Integration

When used in a Poetry project, poethepoet automatically:

Detects Poetry virtual environment
Uses Poetry's dependency isolation
Inherits Poetry configuration

# In a Poetry project
poe test  # Runs in Poetry's virtual environment

UV Integration

When used in a UV project, poethepoet automatically:

Detects UV virtual environment
Uses UV's environment management
Inherits UV configuration

# In a UV project  
poe build  # Runs in UV's virtual environment

Error Handling

The CLI provides detailed error messages for common issues:

# Exit codes returned by CLI
0   # Success
1   # Error (configuration, task not found, execution failure, etc.)

Common error scenarios:

Task not found: Clear message with available tasks
Configuration errors: Specific line/file information
Execution failures: Command and exit code details
Dependency cycles: Dependency chain visualization

Configuration File Discovery

The CLI searches for configuration files in this order:

pyproject.toml (with [tool.poe.tasks] section)
poe_tasks.toml
poe_tasks.yaml
poe_tasks.json

# Override config file location
poe -C /custom/path task_name

# Works with different config formats
poe -C ./config test  # Searches for any supported format

Usage Examples

Basic Task Management

# List all available tasks
poe

# Run specific tasks
poe test
poe lint  
poe build

# Task with arguments
poe serve --host 0.0.0.0 --port 3000

Development Workflow

# Verbose development run
poe -v test

# Quick syntax check (dry run)
poe -d build

# Clean build with executor override
poe -e simple clean build

# Background deployment (quiet)
poe -q deploy

Debugging and Development

# Maximum verbosity for debugging
poe -vvv problematic_task

# Dry run to understand execution
poe -d complex_sequence

# Change directory for debugging
poe -C /tmp/debug_env test

Integration with CI/CD

# Disable colors for log parsing
poe --no-ansi test | tee test-results.log

# Quiet mode for automated systems
poe -q build deploy

# Specific directory execution
poe -C "${WORKSPACE}" test

Install with Tessl CLI

npx tessl i tessl/pypi-poethepoet

docs

cli-usage.md

index.md

plugin-integration.md

programmatic-api.md

task-configuration.md

tile.json