Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Use the CLI safely in scripts without parsing progress messages or table formatting.

​
Prerequisites

  • An authenticated CLI profile or an explicit CI token

​
Workflow

1
Choose JSON, YAML, or name-only output for scripts.
2
Use --page and --per-page, or fetch all pages with --all.
3
Read data from standard output and diagnostics from standard error.
4
Branch on the documented process exit code.

​
Output formats

  • table is the human-readable default.
  • json prints an object containing data and optional pagination meta.
  • yaml prints the same data and meta structure as YAML.
  • name prints one name, slug, key, domain, or ID per line for resource commands.

​
Standard output and standard error

Machine-readable results are written to standard output. Progress, debug traces, prompts, build-follow status, and manifest build logs are written to standard error. --quiet suppresses progress and acknowledgement text. Remote command standard error remains standard error.

​
Pagination

Catalog-backed resource commands accept --page, --per-page, and --all. --per-page is limited to 100. --all is valid only for GET operations and cannot be combined with an explicit page.

​
Retries and cancellation

  • GET, HEAD, and OPTIONS may retry up to three attempts.
  • Writes retry only when the request has an idempotency key.
  • Retryable statuses are 429, 502, 503, and 504; Retry-After is honored.
  • Log streams reconnect after retryable network and server failures using the last event ID.
  • Ctrl-C cancels requests, streams, archive creation, uploads, and polling.

​
Exit codes

  • 0: success.
  • 1: general failure or a remote command exit outside the supported range.
  • 2: CLI usage or flag error.
  • 3: authentication or authorization failure.
  • 4: resource not found.
  • 5: conflict or failed precondition, including stale state.
  • 6: network, timeout, or server failure.
  • 7: partial result, such as a failed diagnostic check.
  • 130: cancelled with Ctrl-C.
  • For stackshift exec, remote exit codes from 1 through 125 are propagated.

​
Secret redaction

Structured output recursively replaces recognized credential, password, private-key, connection-string, secret, and token values with [redacted]. Debug logging also redacts sensitive query parameters and never prints authorization headers.

​
Expected result

Automation receives parseable output and can distinguish usage, auth, conflict, and network failures.

​
Common failures

  • name output is requested for a response that has no named resources.
  • --all is used on a write or a response that is not a paginated array.
  • A script parses table output instead of selecting JSON, YAML, or name output.
  • Progress is redirected from standard output even though it is written to standard error.

Profiles, defaults, and global options

Use profiles for API and resource defaults, then override them explicitly for one command.

Resource command model and coverage

Use consistent list, read, write, pagination, request body, resolution, and confirmation behavior.

Raw customer API command

Call an existing customer API path with bounded inputs, safe retries, downloads, and path restrictions.