taskfile-help 0.3.2

Dynamic Taskfile help generator with automatic grouping and namespace support

taskfile_help

Dynamic Taskfile help generator.

Parses Taskfile YAML files and outputs organized, colored help text similar to task --list, but with automatic grouping and namespace support.

Links:

• Documentation
• GitHub Repository
• Issue Tracker

Why Taskfile Help?

The built-in task --list command is useful, but has limitations:

• No automatic grouping of related tasks
• No namespace support for multiple Taskfiles
• Limited customization options

taskfile-help solves these problems by providing:

• Automatic task grouping using comment markers
• Support for multiple Taskfiles with namespaces
• Flexible search paths and configuration
• JSON output for integration with other tools
• Consistent color handling (respects TTY detection)

Integration with Taskfiles

Designed to be called from Taskfile help tasks. Here's how to integrate it into your workflow:

Basic Setup

Add a help task to your main Taskfile:

version: '3'

tasks:
  # === Main Tasks ===
  build:
    desc: Build the project
    cmds: [...]

  # === Help ===
  help:
    desc: Show available tasks from this Taskfile
    cmd: taskfile-help main
    silent: true  # Suppress task command echo

Now you can run:

task help       # Show available tasks from your main Taskfile nicely grouped and formatted

Multi-Taskfile Setup

The real advantage comes when you have multiple Taskfiles with namespaces.

Start by adding a wildcard help task (help:*): to your main Taskfile:

version: '3'

tasks:
  # ... main tasks ...

  # === Help ===
  help:
    desc: Show available tasks from this main Taskfile
    summary: Displays tasks from this main Taskfile, nicely grouped and formatted
    cmd: taskfile-help main
    silent: true  # Suppress task command echo

  help:*:
    desc: Show available tasks for the given namespace(s)
    summary: |
      Displays tasks from for the given namespace or all Taskfiles if "all" is specified
      or list available namespaces if "?" is specified
      help:<namespace>    - Displays tasks from the given namespace
      help:all            - Displays tasks from all Taskfiles
      help:?              - Lists available namespaces
    vars:
      NAMESPACE: '{{index .MATCH 0}}'
    cmd: taskfile-help {{.NAMESPACE}}
    silent: true  # Suppress task command echo

Now you can run:

task help       # Main tasks only
task help:all   # All tasks from all namespaces (Main + Dev + ...)
task help:<namespace>   # Tasks from the given namespace
task help:?     # List all namespaces (Dev, Test, ...)

Search Integration

You can also add a search wrapper task for convenient searching:

  # === Search ===
  search:*:
    desc: Search for tasks
    summary: Search for tasks in all Taskfiles
    vars:
      PATTERN: '{{index .MATCH 0}}'
    cmd: taskfile-help search {{.PATTERN}}
    silent: true

Now you can search using the task command:

task search:python              # Search for "python"
task search:"version minor"     # Search for both "version" AND "minor"
task search:test                # Search for "test"

Example Output

Usage

Namespace Command

Display tasks from a specific namespace or all namespaces:

# Show help for main Taskfile
taskfile-help namespace
taskfile-help namespace main

# Show help for a specific namespace
taskfile-help namespace dev
taskfile-help namespace rag

# Show help for all Taskfiles
taskfile-help namespace all

# List available namespaces
taskfile-help namespace ?

# With global options (can appear after subcommand)
taskfile-help namespace dev --no-color --verbose
taskfile-help namespace all --json
taskfile-help namespace --search-dirs /path/to/project

Search Command

Search for tasks across namespaces, groups, task names, and descriptions:

# Search by single pattern (case-insensitive substring)
taskfile-help search test
taskfile-help search build

# Search with multiple patterns (AND logic - all must match)
taskfile-help search version bump
taskfile-help search minor version
taskfile-help search test coverage

# Search with regex filter
taskfile-help search --regex "^test"
taskfile-help search --regex ".*fix$"

# Search with multiple regexes (AND logic - all must match)
taskfile-help search --regex "test" --regex "unit"

# Combine patterns and regexes (all must match)
taskfile-help search version --regex "bump"
taskfile-help search test unit --regex "coverage"

# With global options
taskfile-help search build --no-color
taskfile-help search deploy --regex "^deploy" --json --verbose

Search Behavior

• Pattern matching: Case-insensitive substring search
• Regex matching: Full regular expression support
• Multiple patterns: All patterns must match (AND logic)
• Multiple regexes: All regexes must match (AND logic)
• Combined matching: All patterns AND all regexes must match somewhere in the task's combined text
• Search scope: Searches across namespace names, group names, task names, AND descriptions
• At least one filter required: Must provide at least one pattern or regex
• Results: Shows tasks where all search criteria match in any combination of fields

Global Options

Global options can be placed after any subcommand:

• --no-color - Disable colored output
• -s, --search-dirs DIRS - Colon-separated list of directories to search for taskfiles
• -v, --verbose - Show verbose output including search directories
• --json - Output tasks in JSON format
• --completion SHELL - Generate completion script for specified shell (bash, zsh, fish, tcsh, ksh)
• --install-completion [SHELL] - Install completion script (auto-detects shell if not specified)
• -h, --help - Show help message

Shell Completion

taskfile-help supports tab completion for namespaces, task names, and command-line flags in multiple shells.

Quick Install

# Auto-detect shell and install
taskfile-help --install-completion

# Or specify shell explicitly
taskfile-help --install-completion bash

What Gets Completed

• Namespaces: taskfile-help <TAB> shows all available namespaces
• Task names: taskfile-help test:<TAB> shows tasks in the test namespace
• Flags: taskfile-help --<TAB> shows all command-line options

Completions are dynamic and automatically update when you add or remove Taskfiles.

For detailed installation instructions and troubleshooting, see the Shell Completion Documentation.

Configuration

taskfile-help supports multiple configuration methods with a clear priority order.

Configuration Files

taskfile-help supports two configuration file formats:

1. taskfile_help.yml - Dedicated YAML configuration file (takes precedence)
2. pyproject.toml - Python project configuration file (fallback)

If both files exist, taskfile_help.yml takes precedence.

Configuration Matrix

Option	CLI Flag	Environment Variable(s)	Config File	.env File	Default
search-dirs	--search-dirs, -s	TASKFILE_HELP_SEARCH_DIRS	search-dirs	✓	Current directory
no-color	--no-color	NO_COLOR, TASKFILE_HELP_NO_COLOR	no-color	✓	Auto-detect TTY
group-pattern	--group-pattern	TASKFILE_HELP_GROUP_PATTERN	group-pattern	✓	\s*#\s*===\s*(.+?)\s*===
verbose	--verbose, -v	-	-	-	false
json	--json	-	-	-	false

Priority Order: Command-line > Environment Variables > Config File (taskfile_help.yml or pyproject.toml) > Defaults

Configuration Examples

# Using command-line arguments
taskfile-help --no-color --search-dirs /path/to/project

# Using environment variables
export TASKFILE_HELP_SEARCH_DIRS=.:../shared
export NO_COLOR=1
taskfile-help

# Using .env file
cat > .env << EOF
TASKFILE_HELP_SEARCH_DIRS=.:../shared
NO_COLOR=1
EOF
taskfile-help

# Using taskfile_help.yml (recommended)
cat > taskfile_help.yml << EOF
search-dirs:
  - "."
  - "../shared"
no-color: false
group-pattern: "\\\\s*#\\\\s*===\\\\s*(.+?)\\\\s*==="
EOF
taskfile-help

# Using pyproject.toml (alternative)
[tool.taskfile-help]
search-dirs = [".", "../shared"]
no-color = true
group-pattern = "\\\\s*##\\\\s*(.+?)\\\\s*##"

For detailed configuration options, see the Configuration Documentation.

File Naming Conventions

Main Taskfile

Supported names (matches regex [Tt]askfile\.ya?ml):

• Taskfile.yml, Taskfile.yaml (preferred)
• taskfile.yml, taskfile.yaml

Namespace Taskfiles

Supported patterns (matches regex [Tt]askfile[-_](?P<namespace>\w+)\.ya?ml):

• Taskfile-<namespace>.yml, Taskfile-<namespace>.yaml (preferred)
• Taskfile_<namespace>.yml, Taskfile_<namespace>.yaml
• taskfile-<namespace>.yml, taskfile-<namespace>.yaml
• taskfile_<namespace>.yml, taskfile_<namespace>.yaml

Examples: Taskfile-dev.yml, Taskfile_test.yaml, taskfile-rag.yml

Taskfile Discovery

• By default, searches for taskfiles in the current working directory
• Use --search-dirs (or -s) to search in one or more directories (first match wins)
• Paths can be absolute (/path/to/dir) or relative (../dir, ./subdir)
• Relative paths are resolved from the current working directory
• Taskfiles can be located anywhere in the search path(s)

Task Organization

Tasks are automatically grouped using comment markers in the Taskfile:

# === Group Name ===
task-name:
  desc: Task description
  cmds: [...]

task2-name:
  desc: Task2 description
  cmds: [...]

# === Group2 Name ===

Example groups: "Service Management", "Testing", "Build and Release"

The output preserves the order of groups and tasks as they appear in the file.

Task Visibility

• Public tasks: Have a 'desc' field and no 'internal: true' flag
• Internal tasks: Marked with 'internal: true' (excluded from help)
• Tasks without descriptions are excluded from help output

Taskfile Validation

taskfile-help automatically validates Taskfiles to ensure they conform to Task version 3 specification. Validation runs on every parse and produces helpful warnings for issues, but processing continues (non-fatal).

What is Validated

• Version field: Must exist and equal '3' (string, not number)
• Tasks section: Must exist and be a dictionary
• Task structure: Each task must be a dictionary
• Field types: Validates types for common fields:
  • desc: must be a string
  • internal: must be a boolean
  • cmds: must be a list or string
  • deps: must be a list

Example Warnings

$ taskfile-help
Warning: Invalid version '2', expected '3'
Warning: Task 'build': 'desc' must be a string, got int
Warning: Task 'test': 'internal' must be a boolean, got str

# Tasks are still shown despite warnings
MAIN Task Commands:

Build:
  task build            - 123

Validation Behavior

• Always enabled: No opt-in flag required
• Non-fatal: Warnings are displayed but processing continues
• Helpful: Clear messages explain what's wrong and where
• Fast: Minimal performance impact (~1-2ms per file)

All warnings are written to stderr, so they won't interfere with JSON output or piped commands.

Output Behavior

• Colors enabled: When output is to a terminal (TTY) and --no-color is not specified
• Colors disabled: When output is piped, redirected, captured, or --no-color is used
• Matches the behavior of 'task --list'