taskfile-help 0.3.0

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, ...)

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, and task names:

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

# Search by regex
taskfile-help search --regex "^lint"
taskfile-help search --regex ".*fix$"

# Combine multiple filters (AND logic)
taskfile-help search --pattern "test" --regex "unit"

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

Search Behavior

• Pattern matching: Case-insensitive substring search
• Regex matching: Full regular expression support
• Multiple filters: All filters must match (AND logic)
• Search scope: Searches namespace names, group names, and task names
• Results: Shows all tasks in matching namespaces/groups, or individual matching tasks

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

Settings can be configured in pyproject.toml under [tool.taskfile-help]:

[tool.taskfile-help]
search-dirs = [".", "../shared"]  # List of directories to search

Command-line arguments take precedence over pyproject.toml settings.

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'