CLI help text duplication report

cli-help-duplication.md

CLI Help Text Duplication Report

Problem

After externalizing CLI help text to HELP.md files, subcommand listings appear twice in --help output:

usage: viewctl [options] ...

Gist-like file viewer for sharing code snippets.

    create-view  Create a view from one or more files
    serve-views  Start the web server to display views

Subcommands:
  create-view    Create a view from one or more files
  serve-views    Start the web server to display views

1. First listing: Auto-generated by argparse from help= strings in add_parser() calls
2. Second listing: The epilog loaded from HELP.md

Affected CLIs

All 13 CLIs have this duplication to some degree.

Why It Happened

The CLIs use title=argparse.SUPPRESS and description=argparse.SUPPRESS on subparsers, which hides the "subcommands:" header but not the actual listing. The epilog (now in HELP.md) was originally added for richer formatting like costs or categories.

Options to Fix

1. Remove HELP.md entirely - Rely on argparse's auto-generated output. Most HELP.md files are just simple subcommand lists anyway.

2. Keep HELP.md, suppress argparse listing - Add help=argparse.SUPPRESS to each subparser so HELP.md is the only source.

3. Keep both, differentiate content - HELP.md contains only extra info (costs, tips, categories) not duplicated in the basic subcommand list.

CLIs with Richer Epilogs

These have content beyond simple subcommand lists that would be lost with option 1:

• searchctl: Includes per-subcommand costs (~$0.006/query, etc.)
• internalctl: Uses category headers (Task Pipeline:)

Decision

Left as-is for now. Duplication is cosmetic and doesn't break functionality.