CLI Help Generator

You are a CLI documentation expert. The user wants to generate professional help text and man pages for command-line tools.

What to check first

• Verify your CLI tool has a --help or -h flag implemented
• Check if you're using a CLI framework (argparse, commander, Click, yargs) or building from scratch
• Confirm the target output format: simple help text, man page, or both

Steps

1. Choose a CLI framework that supports help generation (Click for Python, Commander for Node, argparse for Python, or cobra for Go)
2. Define your command with a description string and help text for each argument/option
3. Add short flags (-h) and long flags (--help) that trigger the help display
4. Structure help text as: one-line summary, description, usage examples, options list, and footer
5. Use consistent indentation (2-3 spaces) and organize options alphabetically or by category
6. Generate man page metadata if targeting Unix systems (NAME, SYNOPSIS, DESCRIPTION, OPTIONS, EXAMPLES, SEE ALSO sections)
7. Test help output by running your command with --help and verify text wraps properly at 80 characters
8. Add examples section showing real-world usage patterns with expected output

Code

import argparse
from textwrap import dedent

class CLIHelpGenerator:
    def __init__(self, prog_name, version="1.0.0"):
        self.prog_name = prog_name
        self.version = version
    
    def create_parser(self):
        parser = argparse.ArgumentParser(
            prog=self.prog_name,
            description=dedent("""
                Process and transform data files with advanced filtering options.
                Supports JSON, CSV, and YAML formats with real-time validation.
            """).strip(),
            epilog=dedent("""
                Examples:
                  %(prog)s input.json --format json --filter 'active==true'
                  %(prog)s data.csv --output result.json --verbose
                
                For more information, visit: https://example.com/docs
            """).strip(),
            formatter_class=argparse.RawDescriptionHelpFormatter,
            add_help=True
        )
        
        parser.add_argument(
            'input_file',
            help='path to input file (required)'
        )
        
        parser.add_argument(
            '-f', '--format',
            choices=['json', 'csv', 'yaml'],
            default='json',
            help='input file format (default: json)'
        )
        
        parser.add_argument(
            '-o', '--output',
            metavar='FILE',
            help='write results to FILE instead of stdout'
        )
        
        parser.add_argument(
            '--filter',
            metavar='EXPR',
            help='apply filter expression (e.g., "age>30")'
        )
        
        parser.add_argument(

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change