Configuration

taskfile-help can be configured via multiple methods with a clear priority order.

Configuration Methods

taskfile-help supports configuration through:

1. Command-line arguments - Highest priority
2. Environment variables - Shell or .env file
3. Configuration files - taskfile_help.yml (preferred) or pyproject.toml (fallback)
4. Default values - Built-in defaults

Configuration Files

taskfile-help supports two configuration file formats:

taskfile_help.yml (Recommended)

A dedicated YAML configuration file for taskfile-help settings. This file takes precedence over pyproject.toml if both exist.

Example:

# taskfile_help.yml
search-dirs:
  - "."
  - "taskfiles"
  - "../shared"

no-color: false

group-pattern: "\\s*#\\s*===\\s*(.+?)\\s*==="

pyproject.toml (Alternative)

Configuration can also be specified in pyproject.toml under the [tool.taskfile-help] section. This is useful for Python projects that already use pyproject.toml.

Example:

[tool.taskfile-help]
search-dirs = [".", "taskfiles", "../shared"]
no-color = false
group-pattern = "\\s*#\\s*===\\s*(.+?)\\s*==="

File Precedence: If both taskfile_help.yml and pyproject.toml exist in the current directory, taskfile_help.yml takes precedence.

Supported Configuration Options

The following table shows all available configuration options and their supported configuration methods:

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

Note: Environment variables can be set in your shell or in a .env file in the current directory.

Quick 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
TASKFILE_HELP_GROUP_PATTERN=\s*##\s*(.+?)\s*##
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*##"
EOF
taskfile-help

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

Command-Line Options

Namespace Selection

# Show main Taskfile ([Tt]askfile\.ya?ml)
taskfile-help
taskfile-help main

# Show specific namespace ([Tt]askfile[-_](?P<namespace>\w+)\.ya?ml)
taskfile-help dev
taskfile-help test
taskfile-help rag

Show All Taskfiles

taskfile-help all

Displays tasks from all Taskfiles (main + all namespaces).

Color Control

# Disable colors
taskfile-help --no-color

# Colors are automatically disabled when:
# - Output is piped (e.g., taskfile-help | cat)
# - Output is redirected (e.g., taskfile-help > file.txt)
# - Using --json output

Search Directories

# Search in specific directory
taskfile-help --search-dirs /path/to/project
taskfile-help -s /path/to/project

# Search multiple directories (first match wins)
taskfile-help --search-dirs /path1:/path2:/path3
taskfile-help -s ~/projects/main:~/projects/shared

# Relative paths (resolved from current directory)
taskfile-help --search-dirs ../other-project
taskfile-help -s ./subdir:../shared

JSON Output

taskfile-help --json
taskfile-help dev --json

Output format:

{
  "tasks": [
    {
      "group": "Build",
      "name": "build",
      "full_name": "build",
      "description": "Build the project"
    },
    {
      "group": "Build",
      "name": "compile",
      "full_name": "compile",
      "description": "Compile sources"
    }
  ]
}

For namespaces:

{
  "tasks": [
    {
      "group": "Development",
      "name": "serve",
      "full_name": "dev:serve",
      "description": "Start development server"
    }
  ]
}

Verbose Output

taskfile-help --verbose
taskfile-help -v

Shows search directories being used:

Searching in directories:
  /home/user/project
  /home/user/shared

Group Pattern

# Use custom group pattern
taskfile-help --group-pattern '\s*##\s*(.+?)\s*##'

# Use alternative pattern
taskfile-help --group-pattern '\s*#\s*---\s*(.+?)\s*---'

Customize the regular expression pattern used to identify group markers in Taskfiles. The pattern must contain one capture group that extracts the group name.

Configuration File Options

You can configure default settings in either taskfile_help.yml or pyproject.toml:

taskfile_help.yml:

search-dirs:
  - "."
  - "../shared"
  - "~/common"

pyproject.toml:

[tool.taskfile-help]
search-dirs = [".", "../shared", "~/common"]

Configuration Options

search-dirs

List of directories to search for Taskfiles.

taskfile_help.yml:

# Single directory
search-dirs:
  - "."

# Multiple directories
search-dirs:
  - "."
  - "../shared"
  - "~/common"

# Absolute and relative paths
search-dirs:
  - "."
  - "../other-project"
  - "/opt/shared-tasks"
  - "~/my-tasks"

pyproject.toml:

[tool.taskfile-help]
# Single directory
search-dirs = ["."]

# Multiple directories
search-dirs = [".", "../shared", "~/common"]

# Absolute and relative paths
search-dirs = [
    ".",
    "../other-project",
    "/opt/shared-tasks",
    "~/my-tasks"
]

no-color

Disable colored output by default.

taskfile_help.yml:

# Disable colors
no-color: true

# Enable colors (default)
no-color: false

pyproject.toml:

[tool.taskfile-help]
# Disable colors
no-color = true

# Enable colors (default)
no-color = false

group-pattern

Regular expression pattern for identifying group markers in Taskfiles.

taskfile_help.yml:

# Default pattern (matches: # === Group Name ===)
group-pattern: "\\s*#\\s*===\\s*(.+?)\\s*==="

# Custom pattern (matches: ## Group Name ##)
group-pattern: "\\s*##\\s*(.+?)\\s*##"

# Alternative pattern (matches: # --- Group Name ---)
group-pattern: "\\s*#\\s*---\\s*(.+?)\\s*---"

pyproject.toml:

[tool.taskfile-help]
# Default pattern (matches: # === Group Name ===)
group-pattern = "\\s*#\\s*===\\s*(.+?)\\s*==="

# Custom pattern (matches: ## Group Name ##)
group-pattern = "\\s*##\\s*(.+?)\\s*##"

# Alternative pattern (matches: # --- Group Name ---)
group-pattern = "\\s*#\\s*---\\s*(.+?)\\s*---"

The pattern must be a valid regular expression with one capture group that extracts the group name.

Note: Command-line arguments take precedence over environment variables, which take precedence over configuration file settings.

File Naming Conventions

Main Taskfile

The main Taskfile can be named (case-sensitive, matches regex [Tt]askfile\.ya?ml):

• Taskfile.yml
• Taskfile.yaml
• taskfile.yml
• taskfile.yaml

Note: Uppercase variants (Taskfile.*) are preferred and checked first.

Namespace Taskfiles

Namespace Taskfiles follow the pattern (case-sensitive, matches regex [Tt]askfile[-_](?P<namespace>\w+)\.ya?ml):

• Taskfile-<namespace>.yml
• Taskfile-<namespace>.yaml
• Taskfile_<namespace>.yml
• Taskfile_<namespace>.yaml
• taskfile-<namespace>.yml
• taskfile-<namespace>.yaml
• taskfile_<namespace>.yml
• taskfile_<namespace>.yaml

Note: Uppercase variants (Taskfile*) and hyphen separator (-) are preferred.

Examples:

• Taskfile-dev.yml → namespace: dev
• Taskfile_test.yaml → namespace: test
• taskfile-rag.yml → namespace: rag
• Taskfile_agent.yml → namespace: agent

Task Visibility Rules

Public Tasks

Tasks are public (shown in help) when they have:

1. A desc field
2. No internal: true flag

tasks:
  build:
    desc: Build the project  # Public - has desc
    cmds:
      - go build

Internal Tasks

Tasks are internal (hidden from help) when:

1. Marked with internal: true
2. Missing a desc field

tasks:
  _internal:
    desc: Internal helper
    internal: true  # Hidden - marked internal
    cmds:
      - echo "internal"

  no-desc:
    # Hidden - no desc field
    cmds:
      - echo "no description"

Validation

taskfile-help automatically validates Taskfiles to ensure they conform to Task version 3 specification.

What is Validated

Validation checks the following:

1. Version field
2. Must exist

3. Must equal '3' (string, not number or other version)

4. Tasks section

5. Must exist

6. Must be a dictionary

7. Task structure

8. Each task must be a dictionary
9. Field type validation:
   • desc: must be a string
   • internal: must be a boolean (true or false)
   • cmds: must be a list or string
   • deps: must be a list

Validation Behavior

• Always enabled: Validation runs automatically on every parse
• Non-fatal: Warnings are displayed but processing continues
• Clear messages: Explains what's wrong and where
• Fast: Minimal performance impact (~1-2ms per file)

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

Common Issues

Wrong Version

# Wrong - number instead of string
version: 3

# Wrong - version 2
version: '2'

# Correct
version: '3'

Invalid Task Fields

tasks:
  build:
    # Wrong - desc must be a string
    desc: 123

    # Wrong - internal must be boolean
    internal: "yes"

    # Wrong - deps must be a list
    deps: "clean"

  # Correct
  test:
    desc: Run tests
    internal: true
    deps:
      - build
    cmds:
      - pytest

Stderr Output

All validation warnings are written to stderr, so they won't interfere with:

• JSON output (--json)
• Piped commands (taskfile-help | grep ...)
• Redirected output (taskfile-help > file.txt)

Environment Variables

taskfile-help automatically loads environment variables from a .env file in the current directory if it exists. Environment variables set in your shell take precedence over those in the .env file.

NO_COLOR

Standard environment variable to disable colored output (see no-color.org):

# Disable colors using standard NO_COLOR
export NO_COLOR=1
taskfile-help

# One-time use
NO_COLOR=1 taskfile-help

TASKFILE_HELP_NO_COLOR

Alternative taskfile-help specific variable to disable colors:

# Disable colors
export TASKFILE_HELP_NO_COLOR=true
taskfile-help

# Also accepts: 1, yes
TASKFILE_HELP_NO_COLOR=1 taskfile-help

TASKFILE_HELP_SEARCH_DIRS

Set search directories via environment variable (colon-separated):

# Single directory
export TASKFILE_HELP_SEARCH_DIRS=/path/to/project
taskfile-help

# Multiple directories
export TASKFILE_HELP_SEARCH_DIRS=.:/path/to/shared:~/common
taskfile-help

TASKFILE_HELP_GROUP_PATTERN

Set a custom group pattern via environment variable:

# Use custom group pattern
export TASKFILE_HELP_GROUP_PATTERN='\s*##\s*(.+?)\s*##'
taskfile-help

# One-time use
TASKFILE_HELP_GROUP_PATTERN='\s*#\s*---\s*(.+?)\s*---' taskfile-help

Using .env File

You can also set these in a .env file:

# .env
NO_COLOR=1
TASKFILE_HELP_SEARCH_DIRS=.:../shared
TASKFILE_HELP_GROUP_PATTERN=\s*##\s*(.+?)\s*##

Terminal Behavior

taskfile-help respects standard terminal behavior:

• TTY Detection: Automatically detects if output is to a terminal
• Color Support: Colors enabled only when outputting to a TTY
• Pipe Detection: Colors disabled when output is piped or redirected

Search Path Resolution

When searching for Taskfiles:

1. Absolute paths: Used as-is

taskfile-help -s /opt/tasks

1. Relative paths: Resolved from current working directory

taskfile-help -s ../other-project

1. Home directory: Tilde expansion supported

taskfile-help -s ~/my-tasks

1. Multiple paths: First match wins

taskfile-help -s ./local:../shared:/opt/global

Priority Order

Configuration is applied in this order (later overrides earlier):

1. Default values
2. Configuration file (taskfile_help.yml or pyproject.toml)
3. .env file variables
4. Environment variables (shell)
5. Command-line arguments

Config File Precedence: If both taskfile_help.yml and pyproject.toml exist, taskfile_help.yml takes precedence.

Supported Configuration Options:

• search-dirs: --search-dirs, TASKFILE_HELP_SEARCH_DIRS, config file
• no-color: --no-color, NO_COLOR or TASKFILE_HELP_NO_COLOR, config file
• group-pattern: --group-pattern, TASKFILE_HELP_GROUP_PATTERN, config file

Example:

# .env file
NO_COLOR=1
TASKFILE_HELP_SEARCH_DIRS=.:../shared
TASKFILE_HELP_GROUP_PATTERN=\s*##\s*(.+?)\s*##

# taskfile_help.yml (takes precedence over pyproject.toml)
search-dirs:
  - "."
  - "../shared"
no-color: false
group-pattern: "\\s*##\\s*(.+?)\\s*##"

# pyproject.toml (used if taskfile_help.yml doesn't exist)
[tool.taskfile-help]
search-dirs = [".", "../shared"]
no-color = false
group-pattern = "\\s*##\\s*(.+?)\\s*##"

# Shell environment variables override .env and config files
export NO_COLOR=1
export TASKFILE_HELP_SEARCH_DIRS=/custom/path
export TASKFILE_HELP_GROUP_PATTERN='\s*#\s*---\s*(.+?)\s*---'

# Command-line arguments override all
taskfile-help --no-color --search-dirs /other/path --group-pattern '\s*#\s*===\s*(.+?)\s*==='

Examples

Project with Shared Tasks

Using taskfile_help.yml:

# taskfile_help.yml
search-dirs:
  - "."
  - "../shared-tasks"

Using pyproject.toml:

# pyproject.toml
[tool.taskfile-help]
search-dirs = [".", "../shared-tasks"]

# Uses both current dir and shared-tasks
taskfile-help

# Override to use only current dir
taskfile-help --search-dirs .

Multi-Repository Setup

# Search across multiple repos
taskfile-help --search-dirs ~/repos/main:~/repos/shared:~/repos/tools

CI/CD Integration

# Disable colors for CI logs
taskfile-help --no-color

# Export task list as JSON
taskfile-help --json > tasks.json

# Validate Taskfile has tasks
taskfile-help --json | jq '.tasks | length'