CLI Flag Extraction Prompt from Help Text

This prompt is designed for CLI tool maintainers, platform engineers, and technical writers who need to convert raw --help output into a structured, machine-readable JSON catalog of every flag, option, and argument. The primary job-to-be-done is automating the tedious and error-prone process of manually transcribing help text into configuration schemas, API reference docs, or UI form fields. The ideal user has access to the exact help text string from a specific version of a CLI tool and requires a complete, validated schema that captures long/short flags, data types, default values, whether a flag is required, and any mutual exclusion groups.

You should use this prompt when you have a stable, complete block of help text and need a deterministic, structured extraction. It is particularly effective when integrated into a CI/CD pipeline to detect drift between the implemented CLI and its documentation. However, do not use this prompt when the help text is truncated, dynamically generated based on user permissions, or contains locale-specific formatting that the model cannot reliably parse. This prompt is not a substitute for parsing the source code directly when 100% accuracy is required for safety-critical systems; in such cases, use it as a first-pass generator that must be followed by a strict source-code introspection validation harness.

Before executing this prompt, ensure the input help text is complete and unaltered. After extraction, you must validate the output JSON against the original text to confirm no flags were missed and that mutual exclusion rules are correctly represented. The next step is to wire this prompt into an automated harness that compares the extracted schema against a known-good specification or the binary's actual behavior, flagging any discrepancies for human review before the schema is published or used in production tooling.

This prompt template is designed to be dropped directly into your application code. It takes raw --help output as input and produces a structured JSON catalog of all flags, options, and arguments. The template uses square-bracket placeholders that you replace with your specific CLI context, output requirements, and constraints before sending to the model.

textCopy
You are a CLI documentation parser. Your task is to extract every flag, option, and positional argument from the provided help text into a structured JSON schema.

[CONTEXT]
The CLI tool is named [TOOL_NAME]. The help text was generated by running: [HELP_COMMAND]

[INPUT]

[HELP_TEXT]

codeCopy

[OUTPUT_SCHEMA]
Return a JSON object with the following structure:
{
  "tool_name": "string",
  "help_command": "string",
  "flags": [
    {
      "long_flag": "string (e.g., --verbose)",
      "short_flag": "string or null (e.g., -v)",
      "type": "string (boolean, string, integer, count, array)",
      "default": "string or null",
      "required": boolean,
      "description": "string",
      "value_hint": "string or null (e.g., PATH, LEVEL, NAME)",
      "mutually_exclusive_with": ["string (long_flag names)"],
      "deprecated": boolean,
      "deprecation_message": "string or null"
    }
  ],
  "positional_args": [
    {
      "name": "string",
      "required": boolean,
      "multiple": boolean,
      "description": "string",
      "value_hint": "string or null"
    }
  ],
  "subcommands": [
    {
      "name": "string",
      "description": "string",
      "aliases": ["string"]
    }
  ]
}

[CONSTRAINTS]
1. Extract EVERY flag mentioned in the help text. Do not skip any.
2. For boolean flags, set type to "boolean" and default to "false" unless the help text explicitly states otherwise.
3. If a flag accepts a value, set type to "string" unless the help text specifies a different type (integer, count).
4. Infer mutually_exclusive_with groups from phrases like "cannot be used with" or "mutually exclusive with."
5. Mark flags as deprecated if the help text contains words like "deprecated," "will be removed," or "use [alternative] instead."
6. If the help text does not specify a short flag, set short_flag to null.
7. For positional arguments, set multiple to true if the help text indicates the argument can accept multiple values (e.g., "FILE..." or "[FILES]...").
8. If no subcommands are present, return an empty array.
9. Preserve the exact description text from the help output. Do not paraphrase.
10. If you are uncertain about any field, include an "uncertainty_note" field in that object explaining what is ambiguous.

[EXAMPLES]
Input help text:

Usage: mycli [OPTIONS] INPUT [OUTPUT]

Options: -v, --verbose Enable verbose output -o, --output FILE Write output to FILE instead of stdout -q, --quiet Suppress all output --retries N Number of retries (default: 3) --no-color Disable colored output (deprecated, use --color=never)

codeCopy

Expected output:
{
  "tool_name": "mycli",
  "help_command": "mycli --help",
  "flags": [
    {
      "long_flag": "--verbose",
      "short_flag": "-v",
      "type": "boolean",
      "default": "false",
      "required": false,
      "description": "Enable verbose output",
      "value_hint": null,
      "mutually_exclusive_with": [],
      "deprecated": false,
      "deprecation_message": null
    },
    {
      "long_flag": "--output",
      "short_flag": "-o",
      "type": "string",
      "default": null,
      "required": false,
      "description": "Write output to FILE instead of stdout",
      "value_hint": "FILE",
      "mutually_exclusive_with": [],
      "deprecated": false,
      "deprecation_message": null
    },
    {
      "long_flag": "--quiet",
      "short_flag": "-q",
      "type": "boolean",
      "default": "false",
      "required": false,
      "description": "Suppress all output",
      "value_hint": null,
      "mutually_exclusive_with": ["--verbose"],
      "deprecated": false,
      "deprecation_message": null
    },
    {
      "long_flag": "--retries",
      "short_flag": null,
      "type": "integer",
      "default": "3",
      "required": false,
      "description": "Number of retries (default: 3)",
      "value_hint": "N",
      "mutually_exclusive_with": [],
      "deprecated": false,
      "deprecation_message": null
    },
    {
      "long_flag": "--no-color",
      "short_flag": null,
      "type": "boolean",
      "default": "false",
      "required": false,
      "description": "Disable colored output (deprecated, use --color=never)",
      "value_hint": null,
      "mutually_exclusive_with": [],
      "deprecated": true,
      "deprecation_message": "use --color=never"
    }
  ],
  "positional_args": [
    {
      "name": "INPUT",
      "required": true,
      "multiple": false,
      "description": "INPUT",
      "value_hint": null
    },
    {
      "name": "OUTPUT",
      "required": false,
      "multiple": false,
      "description": "OUTPUT",
      "value_hint": null
    }
  ],
  "subcommands": []
}

[RISK_LEVEL]
Medium. Incorrect flag extraction can break downstream tooling that relies on accurate CLI documentation. Always validate the extracted schema against the original help text and test flag combinations for mutual exclusion conflicts.

To adapt this template for your CLI tool, replace the placeholders as follows: [TOOL_NAME] with the name of your CLI binary, [HELP_COMMAND] with the exact command used to generate the help text (e.g., tool --help or tool subcommand --help), and [HELP_TEXT] with the raw help output. If your CLI uses non-standard help formatting, add additional constraints to the [CONSTRAINTS] section describing your specific patterns. For CLIs with deeply nested subcommands, run this prompt once per subcommand and merge the results, using the subcommands array to track the hierarchy. Always validate the extracted schema by comparing the total flag count against the original help text and by testing that mutually exclusive groups do not contain overlapping flags.

The CLI flag extraction prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. The core integration pattern is: capture raw --help output from the target CLI binary (ensuring you capture both stdout and stderr, as some tools emit help text to stderr), pass it to the model with the extraction prompt, validate the returned JSON schema, and then feed the structured flag catalog into your documentation site generator, man page compiler, or API reference system. The harness must treat the model output as a draft that requires mechanical verification before publication.

Build the harness with these concrete checks. Schema validation: validate the returned JSON against a strict schema that requires long_flag, short_flag, type, default, required, description, and mutual_exclusion_group fields for every flag object. Reject any output missing required fields or containing flags not present in the original help text. Flag completeness check: parse the original help text with a regex-based flag extractor (matching patterns like --flag, -f, --flag=VALUE) and compare the set of extracted flags against the model's output. Flag any missing or hallucinated flags for human review. Mutual exclusion validation: for every mutual exclusion group the model identifies, verify that the group members actually appear together in the original help text (look for phrases like "cannot be used with", "mutually exclusive", or grouped option blocks). Default value verification: when the help text explicitly states a default, confirm the model captured it correctly. When the help text is silent on defaults, the model should use null rather than inventing a value. Retry logic: if schema validation fails, retry once with the validation errors appended to the prompt as feedback. If the second attempt also fails, escalate to a human review queue with the original help text, the failed output, and the specific validation errors.

For production use, implement a drift detection loop. Schedule a periodic job (weekly or on each release) that re-extracts help text from the latest CLI binary, runs the extraction prompt, and diffs the new flag catalog against the previously published version. Flag any additions, removals, or description changes for review. This catches undocumented flags, removed flags still in docs, and stale descriptions before users report them. Log every extraction run with the CLI version, help text hash, model version, and validation results. Store these artifacts for auditability. Avoid wiring the prompt directly into a CI/CD publish step without human approval—flag documentation changes should follow the same review process as code changes, especially for breaking flag removals or semantic changes to existing flags.