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

​
Goal

Collect enough verified local and server state to diagnose a CLI failure safely.

​
Prerequisites

  • The StackShift CLI is installed

​
Workflow

1
Inspect the local build and optional server compatibility.
2
Run the structured diagnostic checks.
3
Enable redacted debug output only when request routing needs inspection.
4
Generate a sanitized support bundle and review it before sharing.

​
Version and compatibility

version prints the embedded release version, commit, and build date. --check also fetches the server version, latest CLI, minimum CLI, API version, and manifest version.

​
Doctor checks

doctor checks the active profile, capability endpoint, minimum CLI compatibility, and authenticated user. A failed API check stops later server checks. Any failed check returns exit code 7 after printing the checks completed so far.

​
Support bundle

support-bundle prints structured diagnostics only; it does not create or upload an archive. The output contains generation time, CLI build, OS, architecture, active profile, API URL, server capabilities, and the API error when capability fetching fails. Tokens and configuration secrets are not included. Review API URLs and error text before sharing because they can still describe your environment.

​
Debug output

--debug writes request methods, redacted URLs, browser-open failures, and stream reconnect messages to standard error. Authorization headers are never logged, and sensitive query values are replaced with [redacted].

​
Shell completion

These commands enable completion for the current shell. Add the appropriate command or generated file to your shell configuration only after confirming that shell’s normal completion loading convention.

​
Authentication failures

  • Run stackshift auth status to verify the active profile and credential.
  • Check token-file permissions on Unix; mode 0600 is accepted.
  • Confirm that STACKSHIFT_TOKEN is not unintentionally overriding the profile credential.
  • Run stackshift auth login again after expiry, revocation, or a denied device flow.

​
Configuration and resolution failures

  • Run stackshift context list to inspect the current profile and defaults.
  • Use a UUID when an exact name matches more than one resource.
  • Pass --project, --app, or --environment to test a saved default.
  • Use HTTPS for every non-local API URL.

​
Conflict, network, and partial failures

  • Exit code 5 indicates conflict or failed precondition; regenerate a stale manifest plan.
  • Exit code 6 indicates network, timeout, or server failure; run doctor and inspect debug output.
  • Exit code 7 means diagnostics produced a partial result with at least one failed check.
  • Exit code 130 means the process was cancelled; rerun only after checking remote state.

​
Confirmation failures

Risky operations require an interactive y or yes. In CI, they fail before the API request unless --yes is present. Use --yes only after reviewing the exact target and the command’s plan or request body.

​
Expected result

You can identify configuration, connectivity, compatibility, authentication, or command-input failures.

​
Common failures

  • The installed CLI is below the server minimum version.
  • An environment token silently overrides the intended profile credential.
  • Debug output is mistaken for machine-readable standard output.
  • A support bundle is shared without reviewing API URLs and error details.
  • A cancelled operation is immediately retried without checking server state.

Install and update the StackShift CLI

Install signed releases with Homebrew, Scoop, or the verified release installers and update safely.

Authentication and credential storage

Use browser authorization interactively and explicit, non-persistent token inputs in CI.

Output, pagination, errors, and automation

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