I discovered Cog a couple of years ago and I use it on dozens of my own projects now. It's a really neat thing to have around.

One trick I use a lot is including the output of the "--help" command in the README files for CLI tools that I release.

Here's an example: https://github.com/simonw/ospeak/blob/main/README.md#ospeak-...

View source on that file and you'll see this:

    ## ospeak --help

    <!-- [[[cog
    import cog
    from ospeak import cli
    from click.testing import CliRunner
    runner = CliRunner()
    result = runner.invoke(cli.cli, ["--help"])
    help = result.output.replace("Usage: cli", "Usage: ospeak")
    cog.out(
        "```\n{}\n```".format(help)
    )
    ]]] -->
    ```
    Usage: ospeak [OPTIONS] [TEXT]

      CLI tool for running text through OpenAI Text to speech

      Set the OPENAI_API_KEY environment variable to your OpenAI API key to avoid
      using the --token option every time.

      Example usage:

          ospeak "Everyone deserves a pelican" --voice alloy -x 1.5

    Options:
      --version                       Show the version and exit.
      -v, --voice [alloy|echo|fable|onyx|nova|shimmer|all]
                                      Voice to use
      -o, --output FILE               Save audio to this file on disk
      -x, --speed FLOAT RANGE         Speed of the voice  [0.25<=x<=4.0]
      -s, --speak                     Speak the text even when saving to a file
      --token TEXT                    OpenAI API key
      --help                          Show this message and exit.

    ```
    <!-- [[[end]]] -->

I can now run "cog -r README.md" any time I want to update that block of text in the README.

I also have this line in my GitHub Actions test.yml workflow: https://github.com/simonw/ospeak/blob/73a449d3f006737e72e7a0...

    cog --check README.md

That way my tests will fail if I make a change to the help and forget to update the README.

I like reflecting my help output in my documentation mainly because it's a useful way to review if the help makes sense without having to actually run the command.

I maintain these much larger pages using Cog in a similar way:

- https://docs.datasette.io/en/stable/cli-reference.html

- https://sqlite-utils.datasette.io/en/stable/cli-reference.ht...

- https://llm.datasette.io/en/stable/help.html

I wrote a bit more about this pattern here: https://til.simonwillison.net/python/cog-to-update-help-in-r...