Skip to content

cli/cloud: prefer markdown over JSON in default content negotiation#22963

Merged
julienp merged 1 commit into
masterfrom
mfallihee/prefer-markdown-4tu
May 20, 2026
Merged

cli/cloud: prefer markdown over JSON in default content negotiation#22963
julienp merged 1 commit into
masterfrom
mfallihee/prefer-markdown-4tu

Conversation

@fallimic

@fallimic fallimic commented May 11, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

When pulumi cloud api <op> runs without an explicit --format, prefer text/markdown if the operation's OpenAPI spec declares it; otherwise fall back to the op's primary response content type (still JSON for most endpoints).

Endpoints that author both application/json and text/markdown typically write the markdown as a human / agent friendly rendering of the same data, so defaulting to JSON dumps a schema-shaped payload on the caller when the markdown is what they actually want.

Closes #22958

Test plan

  • Added appropriate unit tests - For all changes
  • Added a test in pkg/engine/lifecycletest - For all engine/protocol changes — N/A, CLI-only change
  • Added a conformance test in pkg/testing/pulumi-test-language - For language protocol changes — N/A
  • Added a golden test in pkg/backend/display - For changes to the output renderers — N/A

pkg/cmd/pulumi/cloud/api_test.go now has TestNegotiateAccept_DefaultPrefersMarkdown (op declares both → returns text/markdown) and TestNegotiateAccept_DefaultFallsBackToJSON (markdown not declared → still JSON). Existing --format=json / --format=markdown / invalid-format / unsupported-format tests are unchanged.

Validation

  • make lint — clean
  • make test_fast — passes for pkg/cmd/pulumi/cloud/... (full make test_fast not run locally)
  • make tidy_fix — clean
  • make format — clean (ran gofumpt -w on the two touched files; no rewrites)
  • Relevant SDK tests pass (if SDK changes) — N/A, no SDK changes
  • make check_proto — clean (if proto changes) — N/A, no proto changes

Changelog

  • Changelog entry added: changelog/pending/20260511--cli-cloud--prefer-markdown-when-endpoint-produces-both.yaml

Risk

Low blast radius.

  • Public CLI surface is preserved: --format flag values and their meanings are unchanged. The only user-visible difference is the default Accept header sent on behalf of endpoints that declare both content types.
  • Server contract: the second Accept value (application/vnd.pulumi+N) advertising CLI capability is still sent unchanged. The Pulumi Cloud service must already handle Accept: text/markdown correctly for these endpoints (it's why they declare it in the spec); if it does not, those endpoints would already break under --format=markdown today.
  • No changes to request bodies, auth, retries, pagination, or error handling.

🤖 Generated with Claude Code

@fallimic fallimic requested a review from fnune May 11, 2026 15:23
@fallimic fallimic marked this pull request as ready for review May 11, 2026 15:23
@fallimic fallimic requested a review from a team as a code owner May 11, 2026 15:23
fnune
fnune approved these changes May 12, 2026
View reviewed changes
Comment thread pkg/cmd/pulumi/cloud/api.go
Comment thread pkg/cmd/pulumi/cloud/api.go Outdated
Comment thread pkg/cmd/pulumi/cloud/api.go Outdated
@pgavlin

pgavlin commented May 12, 2026

Copy link
Copy Markdown
Member

are we sure that this is what we want? is this consistent with other tools? or are we doing something new here?

@pgavlin

pgavlin commented May 12, 2026

Copy link
Copy Markdown
Member

ah I think I glossed completely over this important bit:

if the operation's OpenAPI spec declares it

seems fine then, though I can imagine this being a bit surprising if we start adding markdown to more places. if this is primarily for registry, etc. then I think this is great.

@fallimic

fallimic commented May 12, 2026

Copy link
Copy Markdown
Contributor Author

ah I think I glossed completely over this important bit:

if the operation's OpenAPI spec declares it

seems fine then, though I can imagine this being a bit surprising if we start adding markdown to more places. if this is primarily for registry, etc. then I think this is great.

@pgavlin My thinking is that if an operation is declaring both markdown and json outputs, the markdown is going to be the preferred output for humans and agents. Right now it is only used by the registry APIs.

If we want more control over this behavior in the future we can look into including an ordering in the spec or a setting that users could set in the CLI.

@fallimic fallimic force-pushed the mfallihee/prefer-markdown-4tu branch 3 times, most recently from 3e5bf22 to 7819419 Compare May 13, 2026 14:08
@fallimic
cli/cloud: prefer markdown over JSON in default content negotiation
09de97f 
When `pulumi cloud api` runs without `--format`, prefer `text/markdown`
if the operation's OpenAPI spec declares it; otherwise fall back to the
op's primary response content type (still JSON for most endpoints).
Endpoints that author both formats use markdown as a human/agent
friendly rendering of the same data, so dumping JSON by default is
rarely what the caller wants.

`--format=json`, `--format=markdown`, and JSON-only endpoints are
unchanged.
@fallimic fallimic force-pushed the mfallihee/prefer-markdown-4tu branch from 7819419 to 09de97f Compare May 13, 2026 15:03
@pgavlin

pgavlin commented May 13, 2026

Copy link
Copy Markdown
Member

yeah it's not clear to me whether or not MD is always preferable to JSON for agents--that's the one place I'm not sure here. I think for the registry it makes sense, but for other structured data I'm not confident.

@fnune

fnune commented May 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

@fallimic @pgavlin It would be good to fix this soon, maybe by restricting the effect to just docs commands for now. Our help output (e.g. #22904) and other references to these features mention --output=markdown explicitly so it should be fine, but the default for docs commands being JSON is not great.

@fallimic fallimic added this pull request to the merge queue May 18, 2026
@julienp julienp removed this pull request from the merge queue due to a manual request May 18, 2026
@julienp julienp added this pull request to the merge queue May 20, 2026
Merged via the queue into master with commit 7b362b9 May 20, 2026
120 checks passed
@julienp julienp deleted the mfallihee/prefer-markdown-4tu branch May 20, 2026 13:29
@i-am-tom i-am-tom mentioned this pull request May 22, 2026
Merged
@pulumi-bot

pulumi-bot commented May 22, 2026

Copy link
Copy Markdown
Contributor

This PR has been shipped in release v3.243.0.

@pulumi-bot pulumi-bot mentioned this pull request May 22, 2026
Closed
pull Bot pushed a commit to Stars1233/pulumi that referenced this pull request May 22, 2026
@i-am-tom
Freeze v3.243.0 (pulumi#23332)
ea65a0b 
##  (2026-05-22)


### Features

- [cli] Make the `pulumi project new -y` command write a minimal project
file with no template
  [pulumi#22847](pulumi#22847)

- [cli] Suggest `pulumi neo` in `pulumi preview` and `pulumi up`
diagnostics output
  [pulumi#23326](pulumi#23326)

- [sdk] Add `List` to the Go `plugin.Provider` interface, wired to the
streaming `ResourceProvider.List` RPC
  [pulumi#23287](pulumi#23287)

- [sdkgen] Reserve the package names 'pulumi' and 'input' for internal
use
  [pulumi#23321](pulumi#23321)

- [cli/cloud] Prefer text/markdown over JSON in `pulumi api` when an
endpoint produces both
  [pulumi#22963](pulumi#22963)

- [cli/do] Add resource support to `pulumi do`
  [pulumi#23215](pulumi#23215)

- [cli/neo] Pressing Esc in `pulumi neo` now clears the input box when
it has text; with an empty box, Esc still cancels the agent's current
turn
  [pulumi#23299](pulumi#23299)

- [cli/new] Alias `pulumi new` to `pulumi project new`
  [pulumi#23265](pulumi#23265)


### Bug Fixes

- [cli] Require `--yes` to confirm `pulumi deployment cancel`, `pulumi
stack schedule remove`, `pulumi org webhook remove`, and `pulumi stack
webhook remove` when running non-interactively
  [pulumi#23264](pulumi#23264)

- [pcl] Don't silently ignore `...` in function arguments
  [pulumi#23309](pulumi#23309)

- [sdkgen/nodejs] Cache package references per-deployment in generated
SDKs to fix concurrent inline programs
  [pulumi#23068](pulumi#23068)

- [backend/service] Error out when setting up journaler fails
  [pulumi#22671](pulumi#22671)


### Miscellaneous

- [cli/package] Update the `pulumi package add --agent` documentation
hint to use `<type-token>` as the placeholder for the `/docs/...` URL
  [pulumi#23294](pulumi#23294)

- [cli/plugin] Rename plugin ls to list and rm to remove
  [pulumi#23291](pulumi#23291)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fnune fnune fnune approved these changes
@iwahbe iwahbe iwahbe approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[cloud api] Support text/markdown for docs-related endpoints

6 participants

@fallimic @pgavlin @fnune @pulumi-bot @iwahbe @julienp