CLI Generation: roadmap to Firecrawl-parity for autosdk cli-project

[HavenDV]

Tracking issue: CLI generation quality

AutoSDK already generates runnable CLI projects via autosdk cli-project (and the source-generator variant gated by AutoSDK_GenerateCli=true). For real-world SDKs the generated output is currently a low-level API wrapper: every operation takes only --request-json / --request-file and emits raw JSON. The user-facing UX layer (per-field flags, polling, formatters, sensible output options, env-based auth) has to be re-implemented by hand in every SDK that wants a polished CLI.

Firecrawl is the gold-standard hand-written reference in this org — firecrawl scrape <url> --only-main-content --max-depth 5 --wait --output-dir ./out/ — but its Commands/ folder is ~1500 lines of bespoke System.CommandLine wiring on top of the AutoSDK-generated GeneratedApi/ baseline.

This issue tracks the gap analysis. Each sub-issue captures one missing capability the generator would need to absorb to make hand-written Commands/ largely unnecessary.

Architectural premise (layered approach)

Keep the existing two-tier shape: auto-generated .g.cs baseline + hand-written overrides via partial-class hooks. Each hook becomes optional polish — out-of-the-box generation should already be Firecrawl-quality.

Customization seams:

• partial-class hooks on generated command classes (override formatter, customize argument hoisting, replace command entirely)
• OpenAPI vendor extensions (x-cli-argument, x-cli-format, x-cli-wait, x-cli-skip) for spec-side overrides
• existing AutoSDK CLI/MSBuild flags pattern (AutoSDK_Cli* props mirrored to --cli-* CLI flags)

Gap list

#	Gap	Issue
1	Per-parameter flags (request body flattening)	#339
2	Positional argument hoisting	#340
3	Long-running job polling (--wait/--poll-interval/--wait-timeout)	#341
4	Human-readable response formatters + --json toggle	#342
5	--input / --output / --output-dir convenience options	#343
6	Auth flow polish (env var fallback, per-SDK config dir, auth status with source)	#344
7	Smart command naming (strip tag prefix, drop api wrapper by default)	#345
8	Option set reuse across operations sharing a body schema	#346
9	Tri-state nullable bool option parser	#347
10	Webhook composite builder	#348

Suggested execution order

Land #339 first (request body flattening) — most others depend on it. Then #340 + #345 (hoisting + naming, both small) so the command surface looks right. Then #341 (polling) for the long-running-job SDKs. Then #343 (input/output options). Then #342 (formatters) so the output side is presentable. Then #344 (auth) so SDKs don't need hand-written auth resolution. Finally #346 / #347 / #348 as polish.

Pilot

Firecrawl. Once each gap lands, regenerate Firecrawl.Cli/GeneratedApi/ and shrink the hand-written Commands/ accordingly. Final acceptance is when Firecrawl's CLI ships with no hand-written commands (or only ones that genuinely cannot be derived from the spec).

Reference paths

• Generator: src/libs/AutoSDK.CLI/Commands/CliProjectCommand.cs (scaffolder) and src/libs/AutoSDK.SourceGenerators/CliGenerator.cs (Roslyn).
• Hand-written reference: tryAGI/Firecrawl → src/libs/Firecrawl.Cli/Commands/, CliOptions.cs, CliRuntime.cs.
• Current generated output: tryAGI/Firecrawl → src/libs/Firecrawl.Cli/GeneratedApi/.