fix(cli-generator): disclose the flag name for every property in --schema

[cadesark]

Description

Linear ticket: Refs

Follow-up to #17545, which merged while this was in flight. Both regression agents that verified #17545 independently reported the same gap, and it left one operation whose advertised contract could not be followed at all.

--schema keys properties by wire name, and the flag diverges more often than it looks:

property	actual flag	why
Idempotency-Key	--idempotency-key	header wire-casing
query	--query-param	--query is the JMESPath global, so the spec param gets a -param suffix
any x-fern-parameter-name rename	the renamed flag	override

The query case made the contract literally unfollowable on conversational-ai knowledge-base search — input.required named query, and no --query flag existed for it:

$ elevenlabs conversational-ai knowledge-base search --query x --dry-run
Required parameter 'query' is missing. Provide it via --query-param or --params

An agent had to reimplement the CLI's own sanitisation to get from a property name to a flag — and get the -param suffix and header kebab-casing right. It now reads the flag off the contract:

"query": {"type": "string", "location": "query",
           "description": "The search query text", "flag": "--query-param"}

Derived from the same resolve_param_flag_name the command builder uses, so the two cannot drift. Multipart fields get the same treatment.

flag is absent exactly when the builder registers no flag, which is itself the signal that the property is reachable via --params alone. That is two cases, both mirroring build_resource_command:

• the name cannot be sanitised into a flag at all;
• another wire name claimed the same flag first. The builder keeps the first in sorted order and skips the rest, so the help loop tracks the same flag_to_wire map over the same sorted iteration — otherwise the loser would advertise a flag that sets the winner's parameter.

This is the parameter-loop counterpart to the builtin-collision skip #17545's multipart commit added: one loop in build_operation_schema was honest about builtin collisions and the other was not.

input.required still uses wire names, so the --params route keeps working unchanged.

Changes Made

• sdk/src/openapi/help.rs — emit flag per settable property (parameters and multipart fields); skip it for sdk-variable-bound params, which already advertise globalFlag, and for params whose flag was claimed by an earlier wire name.
• sdk/src/openapi/commands.rs — new resolve_multipart_field_flag_name, called by both the command builder and the help loop. This also closed an existing drift: the builder skipped on is_reserved_flag_name (builtins plus a customer-configured userAgentSuffixFlag) while the help loop only checked BUILTIN_FLAG_NAMES, so a field colliding with the suffix flag was advertised with a flag that is never registered.
• Changelog entry under generators/cli/changes/unreleased/.
• Updated README.md generator (if applicable) — n/a

Testing

• Unit tests added/updated
• Manual testing completed

1945 lib tests pass. every_settable_property_discloses_its_flag covers the builtin-collision suffix, header kebab-casing, an ordinary name, a multipart field, and a cross-parameter collision (pageSize / page_size both resolving to --page-size: the winner discloses it, the loser has no flag), and asserts required still uses wire names.

Verified by regenerating and building the ElevenLabs CLI: 2364 settable properties across 337 operations, 0 missing a flag, and the previously-unfollowable operation now exits 0 from exactly what the contract advertises (--query-param x → query_params=[['query','x']]).

Also re-confirmed on the same build: 0 ancestor-prefix violations in any required list.

Link to Devin session: https://app.devin.ai/sessions/8d3395b13c124d728dc5d615e2149057
Open in Devin Desktop: https://app.devin.ai/desktop/session/8d3395b13c124d728dc5d615e2149057?variant=devin

---

[nitpickybot]

AI Review Summary

Adds a flag field to each settable property in the --schema output, derived from resolve_param_flag_name for parameters and a local kebab for multipart fields. The refactor of the else if into else + a separate variable_reference.is_none() && required check preserves the original required-list semantics. Two issues: an unused closure parameter in the new test (compile warning), and the multipart flag being computed locally rather than via a shared resolver.

• 🟡 2 warning(s)
• 🔵 1 suggestion(s)

---

To request another review, comment /ai-review on this pull request.

[devin-ai-integration]

Devin Review found 1 potential issue.