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

​
Goal

Use a customer API operation that has no higher-level CLI workflow without leaving the customer boundary.

​
Prerequisites

  • An authenticated profile
  • The method, path, and request shape from StackShift customer API documentation

​
Workflow

1
Confirm that no purpose-built CLI command already covers the workflow.
2
Choose an allowed method and customer API path.
3
Supply at most one request body source.
4
Mark a write idempotent only when the API contract guarantees it.
5
Select structured output or a safe download destination.

​
Syntax and allowed methods

The method must be GET, POST, PUT, PATCH, or DELETE. The path must be relative, start with /api/v1/, /v1/, or /v2/, and remain on the configured API host.

​
Blocked paths

Decoded paths are normalized and rejected when they contain traversal. The first path segment after any allowed customer prefix cannot be one of these internal namespaces.
  • admin
  • internal
  • agent
  • webhooks
  • portal
  • compute-runner

​
Request bodies

--data accepts an inline body. --file reads a body from a path, or from standard input when its value is -. Inputs are limited to 16 MiB. The raw command sends the body as application/json but does not invent or transform API fields.

​
Idempotent writes and retries

GET requests may retry automatically. Add --idempotent to a write only when the documented endpoint safely supports repeated requests. The CLI then creates an idempotency key and permits retry on 429, 502, 503, and 504 responses.

​
Downloads

--download is valid only with GET and cannot be combined with request data. The destination is created with mode 0600, existing files are never replaced, and partial files are removed after copy, close, cancellation, or size failure. Raw API downloads are capped at 2 GiB.

​
Output and diagnostics

Non-download responses use the same table, JSON, and YAML printers as resource commands. Sensitive structured fields and query values are redacted. Use --debug to inspect the method and redacted URL on standard error.

​
Expected result

The customer API response is printed or downloaded without permitting internal platform access.

​
Common failures

  • An absolute URL is supplied instead of a relative API path.
  • The path targets a blocked admin, internal, agent, webhook, portal, or runner route.
  • --download is used with a write or request data.
  • The download destination already exists.
  • --idempotent is used without verifying the endpoint contract.

Resource command model and coverage

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

Output, pagination, errors, and automation

Select stable machine output, fetch paginated results, and handle documented exit codes.