Subcommand Tree Generation Prompt from Source Code

This prompt is designed for platform engineers and CLI maintainers who need to document deep, nested subcommand hierarchies that are difficult to trace manually. The primary job-to-be-done is producing a complete, machine-readable map of every command path, including parent-child relationships, aliases, and deprecation markers. The ideal user is someone building a documentation pipeline where this structured output will feed directly into reference pages, shell completion scripts, or automated testing harnesses. Required context includes access to the source code or the ability to run binary introspection commands (like --help on every subcommand) to provide the model with the raw material it needs to analyze.

Use this prompt when you need a single source of truth for your CLI's command structure. It is particularly valuable for tools with multiple levels of subcommands, where manually maintaining a command tree is error-prone and time-consuming. The output is intended to be a JSON schema representing the tree, which can then be programmatically validated against the actual binary. This prompt is not a replacement for hand-written usage examples, conceptual overviews, or tutorials. It is a structural analysis tool. You should avoid using it for simple, flat CLI tools with only a few flags, as the overhead of the prompt and validation harness may outweigh the benefit of a simple manual list.

Before using this prompt, ensure you have a reliable method for extracting the raw command structure. This could be a script that iterates through all discovered subcommands and captures their --help output, or it could be the source code files themselves. The prompt's effectiveness depends on the completeness of this input. After generating the tree, your next step should be to run an automated validation that parses the output and checks for orphaned commands, missing leaf nodes, and incorrect nesting depth against the actual binary. Do not publish the generated tree without this validation step, as even minor source code changes can introduce drift.

This section provides the core prompt you will adapt and integrate into your documentation pipeline. The template is designed to analyze a CLI tool's source code, help text, or runtime introspection output and produce a structured, hierarchical representation of every command, subcommand, alias, and deprecation marker. The output is intended to be machine-readable so it can be ingested by downstream documentation generators, validated against the actual binary, and diffed for drift detection.

textCopy
You are a CLI architecture analyzer. Your task is to generate a complete, hierarchical subcommand tree from the provided source material.

## INPUT
[SOURCE_CODE_OR_INTROSPECTION_OUTPUT]

## CONSTRAINTS
- Output ONLY the command tree in the specified [OUTPUT_SCHEMA]. Do not add commentary.
- Capture the full parent-child relationship for every command, subcommand, and nested subcommand.
- For each node, include: the command name, all known aliases, a brief description derived from help text or comments, and a boolean `deprecated` flag.
- Mark any command flagged as deprecated, hidden, or experimental in the source with the appropriate status.
- Preserve the exact nesting depth. A subcommand of `tool` is distinct from a subcommand of `tool component`.
- If the source material is ambiguous about a command's parent, infer the relationship from usage strings, command registration code, or help text indentation.
- If a command has no subcommands, it is a leaf node. Ensure leaf nodes are not omitted.

## OUTPUT_SCHEMA
```json
{
  "cli_name": "string",
  "version": "string or null",
  "command_tree": [
    {
      "name": "string",
      "aliases": ["string"],
      "description": "string",
      "deprecated": boolean,
      "status": "active | deprecated | hidden | experimental",
      "subcommands": [
        // Recursive self-reference
      ]
    }
  ]
}

EXAMPLES

Input (Go cobra):

goCopy
var rootCmd = &cobra.Command{Use: "mycli", Short: "Root command"}
var getCmd = &cobra.Command{Use: "get [resource]", Aliases: []string{"g"}, Short: "Get a resource"}
var getUsersCmd = &cobra.Command{Use: "users", Short: "Get users"}
getCmd.AddCommand(getUsersCmd)
rootCmd.AddCommand(getCmd)

Output:

jsonCopy
{
  "cli_name": "mycli",
  "command_tree": [
    {
      "name": "mycli",
      "aliases": [],
      "description": "Root command",
      "deprecated": false,
      "status": "active",
      "subcommands": [
        {
          "name": "get",
          "aliases": ["g"],
          "description": "Get a resource",
          "deprecated": false,
          "status": "active",
          "subcommands": [
            {
              "name": "users",
              "aliases": [],
              "description": "Get users",
              "deprecated": false,
              "status": "active",
              "subcommands": []
            }
          ]
        }
      ]
    }
  ]
}

FAILURE MODES TO AVOID

• Do not flatten the tree into a list of commands.
• Do not invent commands not present in the source.
• Do not omit leaf nodes.
• Do not treat aliases as separate commands.

To adapt this template, replace [SOURCE_CODE_OR_INTROSPECTION_OUTPUT] with the actual text you are analyzing—this could be a concatenation of source files, the output of mycli --help run recursively, or a structured introspection dump. Replace [OUTPUT_SCHEMA] if your downstream system expects a different format, such as YAML or a custom JSON schema. For high-risk documentation pipelines where accuracy is critical, always pair this prompt with a validation harness that executes the actual binary to confirm the generated tree matches reality. If the source material exceeds the model's context window, chunk it by top-level command and run the prompt once per chunk, then merge the results programmatically.

Wiring this prompt into an application requires treating the generated command tree as a structured artifact that must pass validation before it reaches documentation. The prompt produces a JSON tree of parent-child relationships, aliases, and deprecation markers, but the harness is responsible for verifying that the tree matches the actual binary's behavior. Start by extracting ground truth from the CLI tool itself: run [TOOL_NAME] --help recursively for every discovered subcommand, capture the raw help text, and build a reference tree of expected commands, flags, and nesting depth. This reference tree becomes your validation source of truth, not the model's output.

The implementation loop follows a clear pattern: extract → prompt → validate → repair or escalate. First, run binary introspection to collect all subcommand paths and their help text. Feed this context into the prompt template along with the expected output schema. Parse the model's JSON response and run three validation passes: (1) completeness check — every command in the reference tree must appear in the generated tree with correct parent-child relationships; (2) orphan detection — no command in the generated tree should lack a valid parent path that traces back to the root; (3) nesting depth verification — the maximum depth in the generated tree must match the reference tree, flagging any missing leaf nodes or incorrectly nested intermediate commands. If validation fails, construct a repair prompt that includes the specific errors, the offending subtree, and the correct parent path from the reference tree. Retry up to two times before escalating to a human reviewer with a structured diff showing what the model got wrong.

Model choice matters here. Use a model with strong JSON schema adherence and long-context handling, since large CLI tools can produce help text that spans tens of thousands of tokens. For tools with more than 50 subcommands, consider chunking the help text by top-level command group and running the prompt once per group, then merging the trees with a reconciliation step that checks for cross-group references and duplicate leaf nodes. Log every prompt invocation, the raw model output, validation results, and any repair attempts. Store these logs alongside the generated tree so that documentation reviewers can trace how each node was produced. The final output should only be committed to documentation after passing all validation checks and, for high-risk or security-sensitive CLI tools, after a human has reviewed the complete tree diff against the previous version.