Rename pulumi cloud api references to pulumi api

[kramhuber]

Proposed changes

The CLI command introduced in #18714 was renamed from pulumi cloud api to top-level pulumi api. This PR updates the docs to match:

• Renames the narrative guide from /docs/iac/cli/cloud-api/ to /docs/iac/cli/api/, with an alias preserving the old URL.
• Updates all text and link references in the CLI overview, Automation API page, access tokens admin page, Cloud REST API reference pages, and /llms.txt.
• Deletes the now-stale auto-generated command pages (pulumi_cloud_api*.md). The renamed files (pulumi_api*.md) will be produced by codegen on the next CLI version bump.
• Scrubs the stale api subcommand references from the auto-generated pulumi_cloud.md page.

One thing left untouched: the cache directory path in the guide (\$PULUMI_HOME/cloud-api-cache/<host>/spec.json) is a filesystem path inside the CLI, not the command name. I didn't have visibility into whether the rename also moved the cache directory, so left it as-is.

Unreleased product version (optional)

Depends on the CLI release that renames pulumi cloud api to pulumi api. Hold until the version bump regenerates content/docs/iac/cli/commands/pulumi_api*.md.

Related issues (optional)

Follow-up to #18714.

[claude]

Docs review for #18917

Summary

The rename is applied consistently. I grepped for stale pulumi cloud api, pulumi_cloud_api, and /docs/iac/cli/cloud-api/ strings across content/, layouts/, data/, and static/ — the only remaining hits are the deliberate alias entry and the cache directory filesystem path you flagged in the PR description. The alias on content/docs/iac/cli/api.md:11-12 correctly preserves the old /docs/iac/cli/cloud-api/ URL.

Issues

1. Internal links to the auto-generated command pages will 404 until the CLI version bump (acknowledged in PR description).

The renamed guide and several other pages link to command-reference pages that don't yet exist in the repo:

• content/docs/iac/cli/api.md:24 → /docs/iac/cli/commands/pulumi_api/
• content/docs/iac/cli/api.md:25 → /docs/iac/cli/commands/pulumi_api_list/
• content/docs/iac/cli/api.md:26 → /docs/iac/cli/commands/pulumi_api_describe/
• content/docs/iac/cli/api.md:187 → /docs/iac/cli/commands/pulumi_api/

These pages are regenerated by CLI codegen, so the broken-link window is expected. The PR description already notes this — just want to make sure the PR isn't merged before the version bump regenerates them.

2. Minor: page title is still Calling the Cloud API.

In content/docs/iac/cli/api.md:2, the nav title remains Calling the Cloud API while the command is now pulumi api. This is defensible — the page is about calling the Cloud REST API, and the h1/title_tag are explicit about that. But a reader scanning the CLI menu for the new command name may not immediately associate the entry with pulumi api. Consider Calling the Pulumi API or leaving as-is; not blocking.

3. Manual scrub of auto-generated pulumi_cloud.md.

content/docs/iac/cli/commands/pulumi_cloud.md is marked auto-generated but is edited by hand here to drop the stale api subcommand mention and SEE ALSO row. That's the right call for the short term; just be aware the next CLI codegen run will rewrite this file, so the behavior depends on whether the CLI release that ships the rename also regenerates pulumi_cloud.md without the old references. If the CLI release lands before that regen, this manual edit might get clobbered back into a stale state. Worth confirming with the CLI release process.

Looks good

• All internal references in content/docs/, layouts/index.llms.txt, and the renamed guide itself were updated consistently.
• The aliases: entry on the renamed file uses the right format and points to the old URL.
• Deleted auto-generated pulumi_cloud_api*.md files had their own redirect aliases (/docs/reference/cli/pulumi_cloud_api*/) in the frontmatter, but those targets will now 404. Low impact since these were auto-generated CLI reference pages that the renamed pulumi_api* regenerated files will replace, but worth noting if you want to add S3 redirects per the project convention for non-Hugo or to-be-removed paths.
• Meta descriptions updated in lockstep with the command rename.
• meta_image and frontmatter structure preserved.

Mention me (@claude) if you'd like another pass once the CLI version bump lands and the pulumi_api* files are regenerated, or for any follow-up fixes.

[claude]

Review: pulumi cloud api → pulumi api rename

The rename is clean and thorough. The narrative guide was correctly moved with an alias preserving the old URL, all in-text and link references across docs and llms.txt are consistent, and the PR description usefully calls out the two open questions (cache-dir path, codegen regeneration timing). A few items to consider before merging:

Possible broken URLs from deleted auto-generated pages

The three deleted command pages (pulumi_cloud_api.md, pulumi_cloud_api_describe.md, pulumi_cloud_api_list.md) leave the following URLs without a redirect:

• /docs/iac/cli/commands/pulumi_cloud_api/
• /docs/iac/cli/commands/pulumi_cloud_api_describe/
• /docs/iac/cli/commands/pulumi_cloud_api_list/
• /docs/reference/cli/pulumi_cloud_api/ (and the _describe / _list variants — these were aliases on the deleted files)

The PR description notes the pages will be regenerated as pulumi_api*.md on the next CLI version bump, which addresses the new location, but not the old URL. Even after codegen runs, the new pages won't automatically carry aliases back to the old paths unless the codegen template handles renames — which it typically doesn't.

For SEO and external links (release notes, blog posts, bookmarks pointing to /docs/iac/cli/commands/pulumi_cloud_api/), consider adding S3 redirects in scripts/redirects/iac-cli-redirects.txt:

docs/iac/cli/commands/pulumi_cloud_api/index.html|/docs/iac/cli/commands/pulumi_api/
docs/iac/cli/commands/pulumi_cloud_api_describe/index.html|/docs/iac/cli/commands/pulumi_api_describe/
docs/iac/cli/commands/pulumi_cloud_api_list/index.html|/docs/iac/cli/commands/pulumi_api_list/
docs/reference/cli/pulumi_cloud_api/index.html|/docs/iac/cli/commands/pulumi_api/
docs/reference/cli/pulumi_cloud_api_describe/index.html|/docs/iac/cli/commands/pulumi_api_describe/
docs/reference/cli/pulumi_cloud_api_list/index.html|/docs/reference/cli/pulumi_api_list/

(Adjust paths to match the redirect file's exact format/conventions.) Alternatively, when the codegen lands, edit the regenerated pulumi_api*.md front matter to include the old paths in aliases.

Cache directory path (content/docs/iac/cli/api.md line 79)

You flagged this in the PR description. The path is currently:

caches it under \$PULUMI_HOME/cloud-api-cache/<host>/spec.json

Worth confirming with the CLI team whether the cache directory was also renamed (e.g., to api-cache/). The rename is reasonable to keep paired so the docs and the on-disk layout don't diverge.

Optional: title front matter

content/docs/iac/cli/api.md line 2 still reads title: Calling the Cloud API. The h1 and title_tag are appropriately more specific ("Calling the Pulumi Cloud REST API from the CLI" / "Pulumi CLI: Calling the Pulumi Cloud REST API"). "Cloud API" here is informal shorthand and reads fine in the left-nav context, so this is more a sanity check than a blocker — leave it if intentional.

Minor

• content/docs/iac/cli/api.md line 12: the aliases list uses two-space-less dash-list style (- /docs/iac/cli/cloud-api/). The pattern across this repo varies; this is consistent with adjacent files, so no action needed.
• Internal link path coverage looks complete — no stragglers in content/, layouts/, or data/ referencing pulumi cloud api, pulumi_cloud_api, or /cli/cloud-api/ (besides the intentional alias).

---

Mention @claude if you'd like another pass or want me to draft the redirect entries directly.

[kramhuber]

@fallimic can you give this a look? there's a lot of auto-generation happening that I'm not familiar with.

[pulumi-bot]

Your site preview for commit 3340a79 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-18917-3340a79e.s3-website.us-west-2.amazonaws.com

[pulumi-bot]

Lighthouse Performance Report

Commit: 3340a79 | Metric definitions

Page	Device	Score	FCP	LCP	TBT	CLS	SI
Homepage	Mobile	🟡 81	2.8s	2.8s	248ms	0.019	6.2s
Homepage	Desktop	🟡 82	0.7s	2.4s	30ms	0.030	2.5s
Install Pulumi	Mobile	🔴 35	5.0s	7.5s	248ms	0.466	7.4s
Install Pulumi	Desktop	🟡 86	1.1s	1.6s	22ms	0.033	2.6s
AWS Get Started	Mobile	🟡 50	4.9s	7.3s	250ms	0.138	6.9s
AWS Get Started	Desktop	🟢 92	1.1s	1.6s	22ms	0.026	1.1s

[fallimic]

I have this one already. Just waiting for the next cli release to ship it #18887