diff --git a/content/docs/administration/access-identity/access-tokens.md b/content/docs/administration/access-identity/access-tokens.md index 3fbd070aae83..0980703348da 100644 --- a/content/docs/administration/access-identity/access-tokens.md +++ b/content/docs/administration/access-identity/access-tokens.md @@ -22,7 +22,7 @@ aliases: Use access tokens to sign into the Pulumi Cloud via the CLI or automate your usage of the Pulumi Cloud using the REST API. Learn more about the REST API in the [Pulumi Cloud REST API docs](/docs/reference/cloud-rest-api/). -The token you use for `pulumi login` also authorizes the [`pulumi cloud api`](/docs/iac/cli/cloud-api/) command, which calls any REST API endpoint directly from the CLI without needing to set the `Authorization` header yourself. +The token you use for `pulumi login` also authorizes the [`pulumi api`](/docs/iac/cli/api/) command, which calls any REST API endpoint directly from the CLI without needing to set the `Authorization` header yourself. Pulumi offers three types of access tokens: diff --git a/content/docs/iac/automation-api/_index.md b/content/docs/iac/automation-api/_index.md index 632e18de9667..112894946519 100644 --- a/content/docs/iac/automation-api/_index.md +++ b/content/docs/iac/automation-api/_index.md @@ -28,7 +28,7 @@ Automation API requires the Pulumi CLI to be installed and available in your `PA {{% /notes %}} {{% notes type="tip" %}} -Automation API drives the Pulumi engine itself, running updates, previews, refreshes, and destroys from a program. If you instead need to read or modify Pulumi Cloud resources (for example, stack metadata, access tokens, or [Insights](/docs/insights/) data) without running a Pulumi program, use [`pulumi cloud api`](/docs/iac/cli/cloud-api/), the CLI command for calling the [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) directly. +Automation API drives the Pulumi engine itself, running updates, previews, refreshes, and destroys from a program. If you instead need to read or modify Pulumi Cloud resources (for example, stack metadata, access tokens, or [Insights](/docs/insights/) data) without running a Pulumi program, use [`pulumi api`](/docs/iac/cli/api/), the CLI command for calling the [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) directly. {{% /notes %}} ## Getting started diff --git a/content/docs/iac/cli/_index.md b/content/docs/iac/cli/_index.md index ff7dc2983356..a2bf22fc5dc2 100644 --- a/content/docs/iac/cli/_index.md +++ b/content/docs/iac/cli/_index.md @@ -47,7 +47,7 @@ The most common commands in the CLI that you'll be using are as follows: * [`pulumi up`](/docs/iac/cli/commands/pulumi_up/): preview and deploy changes to your program and/or infrastructure * [`pulumi preview`](/docs/iac/cli/commands/pulumi_preview/): preview your changes explicitly before deploying * [`pulumi destroy`](/docs/iac/cli/commands/pulumi_destroy/): destroy your program and its infrastructure when you're done -* [`pulumi cloud api`](/docs/iac/cli/cloud-api/): call any [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) endpoint directly from the CLI, with stable exit codes and a JSON error envelope for scripts and agents +* [`pulumi api`](/docs/iac/cli/api/): call any [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) endpoint directly from the CLI, with stable exit codes and a JSON error envelope for scripts and agents ## Complete Reference diff --git a/content/docs/iac/cli/cloud-api.md b/content/docs/iac/cli/api.md similarity index 65% rename from content/docs/iac/cli/cloud-api.md rename to content/docs/iac/cli/api.md index d7ab52010c71..884b17ef788b 100644 --- a/content/docs/iac/cli/cloud-api.md +++ b/content/docs/iac/cli/api.md @@ -1,37 +1,39 @@ --- title: Calling the Cloud API title_tag: "Pulumi CLI: Calling the Pulumi Cloud REST API" -meta_desc: Use pulumi cloud api to call any Pulumi Cloud REST API endpoint from the CLI, with stable exit codes and a JSON error envelope for scripts and agents. +meta_desc: Use pulumi api to call any Pulumi Cloud REST API endpoint from the CLI, with stable exit codes and a JSON error envelope for scripts and agents. h1: Calling the Pulumi Cloud REST API from the CLI menu: iac: parent: iac-cli - identifier: iac-cli-cloud-api + identifier: iac-cli-api weight: 60 +aliases: +- /docs/iac/cli/cloud-api/ meta_image: /images/docs/meta-images/docs-meta.png --- -The [`pulumi cloud api`](/docs/iac/cli/commands/pulumi_cloud_api/) command lets you call any [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) endpoint directly from the CLI. It runs non-interactively, is safe to script, and reuses the credentials you already use with `pulumi login`, so you don't need to manage a separate token to call the API. +The [`pulumi api`](/docs/iac/cli/commands/pulumi_api/) command lets you call any [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) endpoint directly from the CLI. It runs non-interactively, is safe to script, and reuses the credentials you already use with `pulumi login`, so you don't need to manage a separate token to call the API. The command is modeled after [`gh api`](https://cli.github.com/manual/gh_api): you pass a path, an operation ID, or a `METHOD path` row and the CLI handles authentication, headers, path-template substitution, and content negotiation for you. ## Subcommands -`pulumi cloud api` ships in three forms: +`pulumi api` ships in three forms: -* [`pulumi cloud api `](/docs/iac/cli/commands/pulumi_cloud_api/) issues a single HTTP request against the named endpoint. -* [`pulumi cloud api list`](/docs/iac/cli/commands/pulumi_cloud_api_list/) (alias: `ls`) lists every endpoint exposed by the [Pulumi Cloud OpenAPI spec](/docs/reference/cloud-rest-api/). Output is a TTY-friendly table by default; pass `--format=json` to get a stable, scriptable envelope. -* [`pulumi cloud api describe `](/docs/iac/cli/commands/pulumi_cloud_api_describe/) prints the parameters, request body, and response schemas for a single operation. Default output is a human-readable text render; pass `--format=markdown` for a piping-friendly markdown document or `--format=json` for the stable JSON envelope. +* [`pulumi api `](/docs/iac/cli/commands/pulumi_api/) issues a single HTTP request against the named endpoint. +* [`pulumi api list`](/docs/iac/cli/commands/pulumi_api_list/) (alias: `ls`) lists every endpoint exposed by the [Pulumi Cloud OpenAPI spec](/docs/reference/cloud-rest-api/). Output is a TTY-friendly table by default; pass `--format=json` to get a stable, scriptable envelope. +* [`pulumi api describe `](/docs/iac/cli/commands/pulumi_api_describe/) prints the parameters, request body, and response schemas for a single operation. Default output is a human-readable text render; pass `--format=markdown` for a piping-friendly markdown document or `--format=json` for the stable JSON envelope. ## Authentication -`pulumi cloud api` uses the same access token as the rest of the Pulumi CLI. Anything that authorizes `pulumi login` — a personal, organization, or team [access token](/docs/administration/access-identity/access-tokens/), `PULUMI_ACCESS_TOKEN`, or an OIDC-issued token — also authorizes API calls. +`pulumi api` uses the same access token as the rest of the Pulumi CLI. Anything that authorizes `pulumi login` — a personal, organization, or team [access token](/docs/administration/access-identity/access-tokens/), `PULUMI_ACCESS_TOKEN`, or an OIDC-issued token — also authorizes API calls. -If a request requires authentication and the CLI is not authenticated, `pulumi cloud api` exits with code `3` and an error envelope identifying the auth failure. A `401` or `403` response from the API maps to the same exit code. +If a request requires authentication and the CLI is not authenticated, `pulumi api` exits with code `3` and an error envelope identifying the auth failure. A `401` or `403` response from the API maps to the same exit code. ## Path-template substitution -Most Pulumi Cloud endpoints take an organization, project, or stack as part of the URL — for example, `/api/orgs/{orgName}/members`. `pulumi cloud api` resolves each template variable in the following order: +Most Pulumi Cloud endpoints take an organization, project, or stack as part of the URL — for example, `/api/orgs/{orgName}/members`. `pulumi api` resolves each template variable in the following order: 1. A literal value typed directly into the URL (no template variable to fill). 1. A matching `-F` or `-f` field (consumed for the path and not forwarded as a query or body parameter). @@ -40,20 +42,20 @@ Most Pulumi Cloud endpoints take an organization, project, or stack as part of t When a stack is selected, you can usually call: ```bash -pulumi cloud api ListOrganizationMembers +pulumi api ListOrganizationMembers ``` and the CLI fills `{orgName}` from the selected stack automatically. When no project context is available, supply the values with `-F`: ```bash -pulumi cloud api GetStack -F orgName=acme -F projectName=web -F stackName=prod +pulumi api GetStack -F orgName=acme -F projectName=web -F stackName=prod ``` If a path template and a request body field share a parameter name, the first matching `-F` is consumed for the path. Any subsequent `-F` with the same key is sent in the body, so you can pass `-F` twice to fill both. To keep the body fully separate, use `--body` or `--input` instead. ## Request flags -`pulumi cloud api` accepts a `gh api`-style flag set for shaping the request: +`pulumi api` accepts a `gh api`-style flag set for shaping the request: | Flag | Purpose | |---|---| @@ -80,7 +82,7 @@ Pass `--refresh-spec` to any subcommand to force a re-fetch. ## Exit codes and error envelope -`pulumi cloud api` uses the standard [Pulumi CLI exit-code mapping](/docs/iac/cli/exit-codes/). The values it can emit are: +`pulumi api` uses the standard [Pulumi CLI exit-code mapping](/docs/iac/cli/exit-codes/). The values it can emit are: | Exit code | Meaning | |----------:|---------| @@ -100,25 +102,25 @@ On failure, the CLI writes errors to stderr as a single-line JSON envelope with Inspect the currently authenticated user: ```bash -pulumi cloud api /api/user +pulumi api /api/user ``` Call by URL path with template variables filled from `-F`: ```bash -pulumi cloud api /api/orgs/{orgName}/members -F orgName=acme +pulumi api /api/orgs/{orgName}/members -F orgName=acme ``` Call by operation ID — `orgName` is taken from the current Pulumi project: ```bash -pulumi cloud api ListOrganizationMembers +pulumi api ListOrganizationMembers ``` Pass path variables explicitly when no project context is available: ```bash -pulumi cloud api GetStack -F orgName=acme -F projectName=web -F stackName=prod +pulumi api GetStack -F orgName=acme -F projectName=web -F stackName=prod ``` ### Bodies and fields @@ -126,7 +128,7 @@ pulumi cloud api GetStack -F orgName=acme -F projectName=web -F stackName=prod Create a resource via `POST`; body fields are auto-detected from the operation: ```bash -pulumi cloud api CreateOrgToken -F orgName=acme \ +pulumi api CreateOrgToken -F orgName=acme \ -F name=ci-bot -F description="CI deploy token" \ -F admin=false -F expires=0 ``` @@ -134,19 +136,19 @@ pulumi cloud api CreateOrgToken -F orgName=acme \ Send a nested JSON body by mixing scalar fields with an inline JSON literal: ```bash -pulumi cloud api CreateStack -F orgName=acme -F projectName=web \ +pulumi api CreateStack -F orgName=acme -F projectName=web \ -F stackName=prod -F 'tags={"env":"prod","team":"platform"}' ``` Pass an entire request body inline, or read it from a file or stdin: ```bash -pulumi cloud api UpdateStackTags -F orgName=acme -F projectName=web -F stackName=prod \ +pulumi api UpdateStackTags -F orgName=acme -F projectName=web -F stackName=prod \ --body '{"env":"prod","team":"platform"}' -pulumi cloud api UpdateStackTags --input ./tags.json +pulumi api UpdateStackTags --input ./tags.json -cat tags.json | pulumi cloud api UpdateStackTags --input - +cat tags.json | pulumi api UpdateStackTags --input - ``` ### Filtering and pagination @@ -154,13 +156,13 @@ cat tags.json | pulumi cloud api UpdateStackTags --input - Filter the JSON response with `jq`: ```bash -pulumi cloud api /api/user --format=json | jq '.githubLogin' +pulumi api /api/user --format=json | jq '.githubLogin' ``` Walk every page of a paginated endpoint: ```bash -pulumi cloud api ListUserStacks --paginate | jq -r '.stacks[].stackName' +pulumi api ListUserStacks --paginate | jq -r '.stacks[].stackName' ``` ### Discovery and dry-run @@ -168,21 +170,21 @@ pulumi cloud api ListUserStacks --paginate | jq -r '.stacks[].stackName' Browse the API surface and inspect a specific operation: ```bash -pulumi cloud api list --format=json | jq '.operations[] | select(.tag == "Stacks")' +pulumi api list --format=json | jq '.operations[] | select(.tag == "Stacks")' -pulumi cloud api describe CreateOrgToken --format=markdown +pulumi api describe CreateOrgToken --format=markdown ``` Preview the resolved request without sending it: ```bash -pulumi cloud api CreateOrgToken -F orgName=acme \ +pulumi api CreateOrgToken -F orgName=acme \ -F name=ci-bot -F description="CI" -F admin=false -F expires=0 --dry-run ``` ## See also -* [`pulumi cloud api` command reference](/docs/iac/cli/commands/pulumi_cloud_api/) +* [`pulumi api` command reference](/docs/iac/cli/commands/pulumi_api/) * [Pulumi Cloud REST API](/docs/reference/cloud-rest-api/) * [Pulumi Cloud access tokens](/docs/administration/access-identity/access-tokens/) * [Pulumi CLI exit codes](/docs/iac/cli/exit-codes/) diff --git a/content/docs/iac/cli/commands/pulumi_cloud.md b/content/docs/iac/cli/commands/pulumi_cloud.md deleted file mode 100644 index 6adc2271be15..000000000000 --- a/content/docs/iac/cli/commands/pulumi_cloud.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -# This file is auto-generated from github.com/pulumi/pulumi/v3/pkg/cmd/pulumi/markdown -title: "pulumi cloud | CLI commands" -aliases: - - /docs/reference/cli/pulumi_cloud/ -meta_desc: "Learn about the pulumi cloud command." ---- - - - -Interact with Pulumi Cloud - -## Synopsis - -Interact with Pulumi Cloud. - -The `api` subcommand calls any endpoint in the Pulumi Cloud REST API. - -## Options - -``` - -h, --help help for cloud -``` - -## Options inherited from parent commands - -``` - --color string Colorize output. Choices are: always, never, raw, auto (default "auto") - -C, --cwd string Run pulumi as if it had been started in another directory - --disable-integrity-checking Disable integrity checking of checkpoint files - -e, --emoji Enable emojis in the output - -Q, --fully-qualify-stack-names Show fully-qualified stack names - --logflow Flow log settings to child processes (like plugins) - --logtostderr Log to stderr instead of to files - --memprofilerate int Enable more precise (and expensive) memory allocation profiles by setting runtime.MemProfileRate - --non-interactive Disable interactive mode for all commands - --otel-traces string Export OpenTelemetry traces to the specified endpoint. Use file:// for local JSON files, grpc:// for remote collectors - --profiling string Emit CPU and memory profiles and an execution trace to '[filename].[pid].{cpu,mem,trace}', respectively - --tracing file: Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file - -v, --verbose int Enable verbose logging (e.g., v=3); anything >3 is very verbose -``` - -## SEE ALSO - -* [pulumi](/docs/iac/cli/commands/pulumi/) - Pulumi command line -* [pulumi cloud api](/docs/iac/cli/commands/pulumi_cloud_api/) - Call any Pulumi Cloud API endpoint - -###### Auto generated by spf13/cobra on 8-May-2026 diff --git a/content/docs/iac/cli/commands/pulumi_cloud_api.md b/content/docs/iac/cli/commands/pulumi_cloud_api.md deleted file mode 100644 index 78aacda33941..000000000000 --- a/content/docs/iac/cli/commands/pulumi_cloud_api.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -# This file is auto-generated from github.com/pulumi/pulumi/v3/pkg/cmd/pulumi/markdown -title: "pulumi cloud api | CLI commands" -aliases: - - /docs/reference/cli/pulumi_cloud_api/ -meta_desc: "Learn about the pulumi cloud api command." ---- - - - -Call any Pulumi Cloud API endpoint - -## Synopsis - -Call any Pulumi Cloud API endpoint. - -The positional argument may be: a path (with optional {template} variables, e.g. -`/api/orgs/{orgName}/members`), an operation ID as shown in `list` (e.g. -`ListOrgMembers`), or a paste-friendly row (`GET /api/...`). Template variables -are resolved from the current Pulumi project / selected stack, or supplied -with -F (e.g. `-F orgName=acme`). - -Fields provided via -F/--field and -f/--raw-field are sent as query parameters -on GET/HEAD requests and as a JSON request body on POST/PUT/PATCH/DELETE. Method -defaults to GET, or POST when body fields, --body, or --input are present. - -Value forms accepted by -F: - - scalars: `-F name=acme`, `-F count=3`, `-F enabled=true`, `-F note=null` - - nested JSON: `-F 'labels={"env":"prod"}'`, `-F 'tags=["a","b"]'` - - file / stdin: `-F body=@./payload.json`, `-F note=@-` -Use -f/--raw-field to suppress coercion and send the value verbatim as a string. - -For an entire request body, pass --body '' inline, or --input (use -`-` for stdin) to stream from a file. - -A field whose key matches a path template variable (e.g. `-F poolId=123` against -`{poolId}`) fills that variable and is not forwarded as a query or body parameter. -This is the way to supply non-context path parameters when calling by operation -ID. - -When a path template and the request body share a parameter name, the first -matching -F is consumed for the path and any subsequent -F with the same key is -sent in the body. Pass -F twice to fill both, or use --body / --input to supply -the body separately. - -The OpenAPI spec is cached locally for 24 hours; pass --refresh-spec on any -subcommand to force a re-fetch. - -Exit codes: 0 success; 1 caller error; 2 invalid flags; 3 auth; 8 cancelled; -255 internal. - -``` -pulumi cloud api [path-or-operation-id] [flags] -``` - -## Examples - -``` - # Inspect the currently authenticated user. - pulumi cloud api /api/user - - # Call by raw path with template variables filled from -F. - pulumi cloud api /api/orgs/{orgName}/members -F orgName=acme - - # Multiple template variables in the path are filled the same way. - pulumi cloud api /api/stacks/{orgName}/{projectName}/{stackName} \ - -F orgName=acme -F projectName=web -F stackName=prod - - # Call by operation ID — orgName is taken from the current Pulumi project. - pulumi cloud api ListOrgMembers - - # Pass path variables explicitly when no project context is available. - pulumi cloud api GetStack -F orgName=acme -F projectName=web -F stackName=prod - - # Create a resource via POST; body fields go into a JSON body automatically. - pulumi cloud api CreateStackTag -F orgName=acme -F projectName=web \ - -F stackName=prod -F name=env -F value=prod - - # Build a nested body by mixing scalar fields with an inline JSON object. - pulumi cloud api CreateStack -F orgName=acme -F projectName=web \ - -F stackName=prod -F 'tags={"env":"prod","team":"platform"}' - - # Send an array of items using a JSON literal. - pulumi cloud api AddTeamMembers -F orgName=acme -F teamName=eng \ - -F 'members=["alice","bob","carol"]' - - # Pass the entire request body inline with --body. - pulumi cloud api UpdateStack -F orgName=acme -F projectName=web -F stackName=prod \ - --body '{"description":"managed by agent"}' - - # Read a JSON body from a file, or from stdin with `-`. - pulumi cloud api UpdateStackTag --input ./tag.json - cat tag.json | pulumi cloud api UpdateStackTag --input - - - # Filter the JSON response with jq. - pulumi cloud api /api/user --format=json | jq '.githubLogin' - - # Follow pagination cursors and stream the combined result to jq. - pulumi cloud api ListStacks --paginate | jq '.stacks[].name' - - # Extract just the status line + headers without the body. - pulumi cloud api /api/user --include --silent - - # Preview the resolved request without sending it. - pulumi cloud api CreateStackTag -F orgName=acme --dry-run -``` - -## Options - -``` - --body string Inline request body sent verbatim (default Content-Type: application/json). Mutually exclusive with --input - --dry-run Print the resolved request without sending it - --envelope-version int Pin the JSON envelope version the caller expects (default 1) - -F, --field stringArray Typed key=value; numbers/bools/null auto-detected; JSON object/array literals parsed; @file reads file; @- reads stdin. Sent as query params on GET/HEAD, JSON body fields otherwise - --format json Drive content negotiation and rendering. Default uses the op's primary response content type (usually JSON). json or `markdown` request that format via the Accept header — rejected if the op's spec doesn't declare it. `raw` keeps the op's default Accept and writes the body through unchanged. - -H, --header Key: Value Custom HTTP header Key: Value (repeatable) - -h, --help help for api - -i, --include Include HTTP status line and response headers in output - --input - Read request body from file; - reads stdin - -X, --method string HTTP method (default GET, POST when body fields are present) - --paginate Follow pagination cursors and emit the combined result - -f, --raw-field stringArray String key=value with no type coercion. Sent as query params on GET/HEAD, JSON body fields otherwise - --refresh-spec Re-fetch the OpenAPI spec from Pulumi Cloud and overwrite the local cache - --silent Do not print the response body on success; errors are still printed and exit non-zero - --verbose Dump full request and response to stderr -``` - -## Options inherited from parent commands - -``` - --color string Colorize output. Choices are: always, never, raw, auto (default "auto") - -C, --cwd string Run pulumi as if it had been started in another directory - --disable-integrity-checking Disable integrity checking of checkpoint files - -e, --emoji Enable emojis in the output - -Q, --fully-qualify-stack-names Show fully-qualified stack names - --logflow Flow log settings to child processes (like plugins) - --logtostderr Log to stderr instead of to files - --memprofilerate int Enable more precise (and expensive) memory allocation profiles by setting runtime.MemProfileRate - --non-interactive Disable interactive mode for all commands - --otel-traces string Export OpenTelemetry traces to the specified endpoint. Use file:// for local JSON files, grpc:// for remote collectors - --profiling string Emit CPU and memory profiles and an execution trace to '[filename].[pid].{cpu,mem,trace}', respectively - --tracing file: Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file -``` - -## SEE ALSO - -* [pulumi cloud](/docs/iac/cli/commands/pulumi_cloud/) - Interact with Pulumi Cloud -* [pulumi cloud api describe](/docs/iac/cli/commands/pulumi_cloud_api_describe/) - Show the parameters and schemas for a Pulumi Cloud API operation -* [pulumi cloud api list](/docs/iac/cli/commands/pulumi_cloud_api_list/) - List every Pulumi Cloud API endpoint - -###### Auto generated by spf13/cobra on 8-May-2026 diff --git a/content/docs/iac/cli/commands/pulumi_cloud_api_describe.md b/content/docs/iac/cli/commands/pulumi_cloud_api_describe.md deleted file mode 100644 index fde5d5b0b1c2..000000000000 --- a/content/docs/iac/cli/commands/pulumi_cloud_api_describe.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -# This file is auto-generated from github.com/pulumi/pulumi/v3/pkg/cmd/pulumi/markdown -title: "pulumi cloud api describe | CLI commands" -aliases: - - /docs/reference/cli/pulumi_cloud_api_describe/ -meta_desc: "Learn about the pulumi cloud api describe command." ---- - - - -Show the parameters and schemas for a Pulumi Cloud API operation - -## Synopsis - -Show the parameters, request body, and response schema for a Pulumi Cloud -API operation. - -The argument may be either a path (with optional template variables, e.g. -`/api/stacks/{orgName}`) or an operation ID as shown in `list` (e.g. -`ListAccounts`). Operation IDs are matched case-insensitively. - -Default output is a human-readable schema render. Pass --format=json for the -stable agent envelope, including the inlined JSON schema. - -``` -pulumi cloud api describe [flags] -``` - -## Examples - -``` - # Describe an operation by its ID. - pulumi cloud api describe ListOrgMembers - - # Describe by path — use --method when the same path maps to multiple ops. - pulumi cloud api describe /api/orgs/{orgName}/members --method=POST - - # Paste-friendly: copy a METHOD + path row from `list` verbatim. - pulumi cloud api describe 'GET /api/user' - - # Extract just the request body schema. - pulumi cloud api describe CreateStackTag --format=json | jq '.operation.requestBody.jsonSchema' - - # Pull the parameter list for scripting. - pulumi cloud api describe GetStack --format=json | jq '.operation.parameters[] | {name, in, required}' -``` - -## Options - -``` - --format markdown Output format: default is a human-readable schema render; markdown emits a markdown document (piping friendly, renders in IDEs/glow); `json` emits the stable agent envelope - -h, --help help for describe - -X, --method string HTTP method to look up (a path can map to multiple ops by method) (default "GET") -``` - -## Options inherited from parent commands - -``` - --color string Colorize output. Choices are: always, never, raw, auto (default "auto") - -C, --cwd string Run pulumi as if it had been started in another directory - --disable-integrity-checking Disable integrity checking of checkpoint files - -e, --emoji Enable emojis in the output - -Q, --fully-qualify-stack-names Show fully-qualified stack names - --logflow Flow log settings to child processes (like plugins) - --logtostderr Log to stderr instead of to files - --memprofilerate int Enable more precise (and expensive) memory allocation profiles by setting runtime.MemProfileRate - --non-interactive Disable interactive mode for all commands - --otel-traces string Export OpenTelemetry traces to the specified endpoint. Use file:// for local JSON files, grpc:// for remote collectors - --profiling string Emit CPU and memory profiles and an execution trace to '[filename].[pid].{cpu,mem,trace}', respectively - --refresh-spec Re-fetch the OpenAPI spec from Pulumi Cloud and overwrite the local cache - --tracing file: Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file - -v, --verbose int Enable verbose logging (e.g., v=3); anything >3 is very verbose -``` - -## SEE ALSO - -* [pulumi cloud api](/docs/iac/cli/commands/pulumi_cloud_api/) - Call any Pulumi Cloud API endpoint - -###### Auto generated by spf13/cobra on 8-May-2026 diff --git a/content/docs/iac/cli/commands/pulumi_cloud_api_list.md b/content/docs/iac/cli/commands/pulumi_cloud_api_list.md deleted file mode 100644 index 7572113c3de1..000000000000 --- a/content/docs/iac/cli/commands/pulumi_cloud_api_list.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -# This file is auto-generated from github.com/pulumi/pulumi/v3/pkg/cmd/pulumi/markdown -title: "pulumi cloud api list | CLI commands" -aliases: - - /docs/reference/cli/pulumi_cloud_api_list/ -meta_desc: "Learn about the pulumi cloud api list command." ---- - - - -List every Pulumi Cloud API endpoint - -## Synopsis - -List every endpoint exposed by the Pulumi Cloud OpenAPI spec. - -Output is sorted by (tag asc, path asc, method precedence). The default is a -human-readable table when interactive; when non-interactive, list switches to -the JSON envelope so downstream parsers don't have to deal with the table's -box-drawing characters. Pass --format=json to request JSON explicitly, or ---format=table to keep the table when redirecting. - -Preview endpoints are listed by default; deprecated endpoints are hidden. Use ---include-preview=false or --include-deprecated to change that. - -``` -pulumi cloud api list [flags] -``` - -## Examples - -``` - # Print the table of stable endpoints. - pulumi cloud api list - - # Grab every operation as JSON (the default when piped). - pulumi cloud api list --format=json - - # Count endpoints per tag with jq. - pulumi cloud api list --format=json | jq '[.operations[] | .tag] | group_by(.) | - map({tag: .[0], count: length})' - - # Find all stack-related GETs. - pulumi cloud api list --format=json | jq '.operations[] | - select(.method=="GET" and (.path | contains("/stacks"))) | .operationId' - - # Full-text search descriptions for deployment-related endpoints. - pulumi cloud api list --format=json | jq '.operations[] | - select(.description | test("deployment"; "i")) | - {operationId, path, description}' - - # Include deprecated endpoints (hidden by default). - pulumi cloud api list --include-deprecated - - # Hide preview endpoints. - pulumi cloud api list --include-preview=false -``` - -## Options - -``` - --format table Output format: table (human-readable, default when interactive), `json` (stable agent envelope, default when non-interactive). Use --format=table to keep the table when redirecting. - -h, --help help for list - --include-deprecated Include endpoints marked as deprecated - --include-preview Include endpoints marked as preview (default true) -``` - -## Options inherited from parent commands - -``` - --color string Colorize output. Choices are: always, never, raw, auto (default "auto") - -C, --cwd string Run pulumi as if it had been started in another directory - --disable-integrity-checking Disable integrity checking of checkpoint files - -e, --emoji Enable emojis in the output - -Q, --fully-qualify-stack-names Show fully-qualified stack names - --logflow Flow log settings to child processes (like plugins) - --logtostderr Log to stderr instead of to files - --memprofilerate int Enable more precise (and expensive) memory allocation profiles by setting runtime.MemProfileRate - --non-interactive Disable interactive mode for all commands - --otel-traces string Export OpenTelemetry traces to the specified endpoint. Use file:// for local JSON files, grpc:// for remote collectors - --profiling string Emit CPU and memory profiles and an execution trace to '[filename].[pid].{cpu,mem,trace}', respectively - --refresh-spec Re-fetch the OpenAPI spec from Pulumi Cloud and overwrite the local cache - --tracing file: Emit tracing to the specified endpoint. Use the file: scheme to write tracing data to a local file - -v, --verbose int Enable verbose logging (e.g., v=3); anything >3 is very verbose -``` - -## SEE ALSO - -* [pulumi cloud api](/docs/iac/cli/commands/pulumi_cloud_api/) - Call any Pulumi Cloud API endpoint - -###### Auto generated by spf13/cobra on 8-May-2026 diff --git a/content/docs/reference/cloud-rest-api/_index.md b/content/docs/reference/cloud-rest-api/_index.md index 115f94cd4d7b..22c37d24b036 100644 --- a/content/docs/reference/cloud-rest-api/_index.md +++ b/content/docs/reference/cloud-rest-api/_index.md @@ -1,6 +1,6 @@ --- title_tag: "Pulumi Cloud: REST API Reference" -meta_desc: Overview of the Pulumi Cloud REST API. Query organization, stack, and state data; call any endpoint from the pulumi cloud api CLI. +meta_desc: Overview of the Pulumi Cloud REST API. Query organization, stack, and state data; call any endpoint from the pulumi api CLI. title: "REST API Docs" h1: Pulumi Cloud REST API meta_image: /images/docs/meta-images/docs-meta.png @@ -30,7 +30,7 @@ aliases: You can call any endpoint two ways: -* **From the CLI** — use [`pulumi cloud api`](/docs/iac/cli/cloud-api/), which inherits your existing CLI credentials, fills `{orgName}`/`{projectName}`/`{stackName}` from the selected stack, and returns a stable JSON error envelope and exit codes that scripts and agents can rely on. Run `pulumi cloud api list` to browse endpoints and `pulumi cloud api describe ` to inspect a specific operation. +* **From the CLI** — use [`pulumi api`](/docs/iac/cli/api/), which inherits your existing CLI credentials, fills `{orgName}`/`{projectName}`/`{stackName}` from the selected stack, and returns a stable JSON error envelope and exit codes that scripts and agents can rely on. Run `pulumi api list` to browse endpoints and `pulumi api describe ` to inspect a specific operation. * **Directly over HTTPS** — pair an [access token](/docs/administration/access-identity/access-tokens/) with the standard `Accept` and `Content-Type` headers and call the endpoint with `curl` or any HTTP client. ## API documentation by category diff --git a/content/docs/reference/cloud-rest-api/api-basics/_index.md b/content/docs/reference/cloud-rest-api/api-basics/_index.md index 9bde56fda555..06a6cd8c7b23 100644 --- a/content/docs/reference/cloud-rest-api/api-basics/_index.md +++ b/content/docs/reference/cloud-rest-api/api-basics/_index.md @@ -1,7 +1,7 @@ --- title: API Basics title_tag: "Pulumi Cloud REST API: API Basics" -meta_desc: The Pulumi Cloud REST API endpoint, authentication, and required headers, plus equivalent calls from the pulumi cloud api CLI command. +meta_desc: The Pulumi Cloud REST API endpoint, authentication, and required headers, plus equivalent calls from the pulumi api CLI command. menu: reference: parent: cloud-rest-api @@ -48,7 +48,7 @@ Content-Type: application/json ## Calling the API from the CLI -The [`pulumi cloud api`](/docs/iac/cli/cloud-api/) command wraps the REST API so you don't have to assemble the headers, base URL, or path-template variables yourself. It uses the same credentials as the rest of the Pulumi CLI, so any token you already use with `pulumi login` is reused automatically. +The [`pulumi api`](/docs/iac/cli/api/) command wraps the REST API so you don't have to assemble the headers, base URL, or path-template variables yourself. It uses the same credentials as the rest of the Pulumi CLI, so any token you already use with `pulumi login` is reused automatically. For example, the following two calls are equivalent: @@ -59,7 +59,7 @@ curl -H "Authorization: token $PULUMI_ACCESS_TOKEN" \ https://api.pulumi.com/api/user # Same call from the Pulumi CLI -pulumi cloud api /api/user +pulumi api /api/user ``` -`pulumi cloud api list` (alias: `ls`) lists every endpoint in the OpenAPI spec, and `pulumi cloud api describe ` prints the parameter, request, and response schemas for a single operation. See the [`pulumi cloud api` guide](/docs/iac/cli/cloud-api/) for the full set of flags, output formats, and the agent-facing error envelope. +`pulumi api list` (alias: `ls`) lists every endpoint in the OpenAPI spec, and `pulumi api describe ` prints the parameter, request, and response schemas for a single operation. See the [`pulumi api` guide](/docs/iac/cli/api/) for the full set of flags, output formats, and the agent-facing error envelope. diff --git a/layouts/index.llms.txt b/layouts/index.llms.txt index f75ebd2ca35d..47f2b2691a8a 100644 --- a/layouts/index.llms.txt +++ b/layouts/index.llms.txt @@ -8,18 +8,18 @@ Pulumi is an open source infrastructure as code platform that lets you use famil If you are an AI agent or programmatic consumer, start with these endpoints. Each has a copy-pasteable example. -- **Pulumi Cloud REST API (via the CLI)** — call any [Pulumi Cloud REST API](https://www.pulumi.com/docs/reference/cloud-rest-api/) endpoint with [`pulumi cloud api`](https://www.pulumi.com/docs/iac/cli/cloud-api/). The command emits a stable JSON error envelope and stable [exit codes](https://www.pulumi.com/docs/iac/cli/exit-codes/) for agent consumers, and `pulumi cloud api list --format=json` returns the full endpoint catalog. Authentication reuses the existing Pulumi CLI credentials. +- **Pulumi Cloud REST API (via the CLI)** — call any [Pulumi Cloud REST API](https://www.pulumi.com/docs/reference/cloud-rest-api/) endpoint with [`pulumi api`](https://www.pulumi.com/docs/iac/cli/api/). The command emits a stable JSON error envelope and stable [exit codes](https://www.pulumi.com/docs/iac/cli/exit-codes/) for agent consumers, and `pulumi api list --format=json` returns the full endpoint catalog. Authentication reuses the existing Pulumi CLI credentials. - pulumi cloud api list --format=json - pulumi cloud api describe --format=json - pulumi cloud api /api/user + pulumi api list --format=json + pulumi api describe --format=json + pulumi api /api/user - **Cloud registry API** — every published package, version-by-version. Public packages need no auth; set `Authorization: token $PULUMI_ACCESS_TOKEN` for private. Works without the CLI. # CLI (auto-fills lang/os from project runtime + host OS) - pulumi cloud api ls | grep registry - pulumi cloud api describe ListPackageVersions - pulumi cloud api /api/registry/packages/pulumi/pulumi/aws/versions/latest/readme + pulumi api ls | grep registry + pulumi api describe ListPackageVersions + pulumi api /api/registry/packages/pulumi/pulumi/aws/versions/latest/readme # Direct HTTP (markdown variant via Accept header) curl -H "Accept: text/markdown" \ @@ -47,7 +47,7 @@ If you are an AI agent or programmatic consumer, start with these endpoints. Eac - **Provider schemas** — full Pulumi schema for any provider, including resource types, input/output shapes, function signatures, and language-specific type mappings. The cloud registry API's `versions/{version}` response includes a `schemaURL` field — follow it for the version-pinned schema. `pulumi package get-schema` accepts `[@version]`, a plugin binary or folder path, or a local `.json` / `.yaml` schema file. The static URL is latest-only. # Versioned (via cloud registry API) - pulumi cloud api /api/registry/packages/pulumi/pulumi/aws/versions/6.0.0 \ + pulumi api /api/registry/packages/pulumi/pulumi/aws/versions/6.0.0 \ | jq -r .schemaURL | xargs curl pulumi package get-schema aws