Skip to content

feat: show request body examples in generated command help - #966

Open
aengelberg wants to merge 1 commit into
mainfrom
ae/help-request-examples
Open

aengelberg wants to merge 1 commit into
mainfrom
ae/help-request-examples

Conversation

@aengelberg

@aengelberg aengelberg commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Context

The help for a generated command that takes --data says only "Input data in JSON". It does not show the JSON that the endpoint accepts.

Why I care: I'm concerned that commands that are --data-heavy (specifically the new environment-releases-beta) are going to be really hard for agents to use because there's no info about what the data needs to look like.

The OpenAPI spec already has request body examples for many of these endpoints. For example, startEnvironmentRelease has four named examples, one for each type of release.

With these changes

The generator reads the request body examples of each operation, and each command shows them in the Examples section of its help:

$ ldcli environment-releases-beta stop --help
...
Examples:
  # Revert every started phase and remove pending phases
  ldcli environment-releases-beta stop --project <project> --flag <flag> --environment <environment> --release-id <release-id> --data '{
    "comment": "Error rate regressed after the 10% step",
    "resolution": "roll_back_all_phases_and_remove_pending_phases"
  }'

  # Serve the target variation everywhere, including pending phases
  ldcli environment-releases-beta stop --project <project> --flag <flag> --environment <environment> --release-id <release-id> --data '{
    "resolution": "roll_forward_all_phases"
  }'
  • The generator uses the media type example and the named examples, with the summary of each named example as a comment line. It does not use schema examples, because many of them are generated placeholder values such as "metricKey": "metricKey".
  • Each example is a full command with the required flags, so you can copy it and replace the placeholders. The command escapes single quotes in the JSON for the shell.
  • The JSON keys are in alphabetical order. The spec decoder does not keep the key order of the spec.
  • 53 commands now have help examples. Commands without request body examples do not change.

Testing

  • go test ./... passes. A new test gets the example from ldcli teams create --help, runs it with a mock client, and checks that the command sends the example JSON.
  • I ran the four environment-releases-beta start examples through sh. Each one parsed and sent its request to the correct URL.

🤖 Generated with Claude Code


Note

Overview
Generated resource commands now surface copy-pasteable --data examples in each subcommand’s Examples section instead of only describing JSON generically.

The OpenAPI generator pulls application/json request body example and named examples (summaries become # comment lines), stores them on OperationData.Examples, and buildExample turns them into full commands with required/path flags, indented JSON, and shell-safe single-quote escaping. The codegen template embeds examples into resource_cmds.go for dozens of body-bearing operations (including multi-example flows like environment releases).

Tests cover buildExample formatting/escaping and verify teams create --help example JSON is accepted by a mock client.

Reviewed by Cursor Bugbot for commit 5d99cbc. Bugbot is set up for automated code reviews on this repo. Configure here.

@aengelberg
aengelberg added this pull request to stack #965 October 23, 2026 22:24
@aengelberg
aengelberg force-pushed the ae/help-request-examples branch from 5b810bc to 642df58 Compare October 23, 2026 22:24
@aengelberg
aengelberg marked this pull request as ready for review October 23, 2026 22:37
@aengelberg
aengelberg requested a review from a team as a code owner October 23, 2026 22:37
@aengelberg
aengelberg requested review from btesfamariam and removed request for a team October 23, 2026 22:37

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 642df58. Configure here.

for _, ex := range op.Examples {
data := strings.ReplaceAll(ex.Data, "'", `'\''`)
data = strings.ReplaceAll(data, "\n", "\n ")
example := fmt.Sprintf(" %s --%s '%s'", cmdLine, cliflags.DataFlag, data)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Help examples omit semantic-patch flag

Medium Severity

buildExample builds a copy-paste command from path flags and --data only, and never adds --semantic-patch. Several generated help examples use an instructions body that the API accepts only with the semantic-patch content type, so those commands fail when run as shown.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 642df58. Configure here.

Base automatically changed from ae/sync-openapi-spec-environment-releases to main November 2, 2026 20:04
The generator now reads the request body examples of each operation in
the OpenAPI spec. Each generated command shows them in the Examples
section of its help, as a full command with the required flags and the
example JSON in --data.

The generator uses the media type example and the named examples. It
does not use schema examples. 53 commands now have help examples.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@aengelberg
aengelberg force-pushed the ae/help-request-examples branch from 642df58 to 5d99cbc Compare November 2, 2026 20:04
@aengelberg

Copy link
Copy Markdown
Contributor Author

bumping @btesfamariam @nieblara

@btesfamariam
btesfamariam requested a review from nieblara November 5, 2026 19:55
@btesfamariam

Copy link
Copy Markdown

running ldcli members update-multiple --help or ldcli teams-beta update-multiple --help, copies the sample, and fills in real member or team ids. LD answers with a 400: the request is missing domain-model=launchdarkly.semanticpatch`. The command already has a switch for it, --semantic-patch, but the sample leaves the switch off, so the tool sends an ordinary JSON request.

also, running ldcli applications-beta update-version --help copies the sample, and sets value to the text "false". That field is a real true/false value. With the quotes, LaunchDarkly returns 400, request body contains invalid JSON.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants