Detect

GUI4CLI does not ask an LLM what the flags are. It reads the file.

Order

1. Commander — static AST (option, argument, required, defaults, choices)
2. yargs — same idea (option, alias, choices, demandOption)
3. JSDoc — @param tags (first-pass; thin)
4. Config fields — gui4cli.config.js or gui4cli.json next to the script. Nonempty explicit fields skip target execution for --help. Config overrides matching static fields and adds new ones.
5. --help — if static detection and config fields found no fields, GUI4CLI may execute the script with --help and stop waiting after a timeout. That execution can have side effects. Use scripts you trust. A hang or an error does not undo work the script already did. Presentation-only config does not skip this fallback.

Commander wins when it finds at least as many fields as yargs. Empty detect plus no config throws a plain error and tells you to add a config file.

--json skips the window, not the detection pipeline. Use it in CI.

Config

When the script builds flags at runtime, write the fields yourself:

// gui4cli.config.js
export default {
  title: 'Resize',
  fields: [
    { name: 'width', type: 'number', required: true, default: 800 },
    { name: 'height', type: 'number', default: 600 },
    { name: 'out', type: 'file', longFlag: '--out' }
  ]
};

Zod validates the merged form before the window opens.

Field types

What detect does not do

It does not reverse-engineer highly dynamic CLIs, walk subcommands, or treat a failed --help spawn as a crash. Those scripts need config. Unknown flags are omitted, not guessed into the form.