> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnostics, completion, and troubleshooting

> Check version compatibility, produce sanitized diagnostics, install completion, and resolve common failures.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

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

## Prerequisites

* The StackShift CLI is installed

## Workflow

<Steps>
  <Step>
    Inspect the local build and optional server compatibility.
  </Step>

  <Step>
    Run the structured diagnostic checks.
  </Step>

  <Step>
    Enable redacted debug output only when request routing needs inspection.
  </Step>

  <Step>
    Generate a sanitized support bundle and review it before sharing.
  </Step>
</Steps>

## 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.

```bash theme={null}
stackshift version
stackshift version --check
stackshift version --check -o json
```

## 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.

```bash theme={null}
stackshift doctor
stackshift doctor -o json
```

## 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.

```bash theme={null}
stackshift support-bundle -o json > stackshift-support.json
```

## 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]`.

```bash theme={null}
stackshift --debug project list -o json 2> stackshift-debug.log
```

## 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.

<CodeGroup>
  ```bash Bash theme={null}
  source <(stackshift completion bash)
  ```

  ```bash Zsh theme={null}
  source <(stackshift completion zsh)
  ```

  ```fish Fish theme={null}
  stackshift completion fish | source
  ```

  ```powershell PowerShell theme={null}
  stackshift completion powershell | Out-String | Invoke-Expression
  ```
</CodeGroup>

## 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

<Check>
  You can identify configuration, connectivity, compatibility, authentication, or command-input failures.
</Check>

## Common failures

<Warning>
  * 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.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Install and update the StackShift CLI" href="/cli/installation">
    Install signed releases with Homebrew, Scoop, or the verified release installers and update safely.
  </Card>

  <Card title="Authentication and credential storage" href="/cli/authentication">
    Use browser authorization interactively and explicit, non-persistent token inputs in CI.
  </Card>

  <Card title="Output, pagination, errors, and automation" href="/cli/output-and-automation">
    Select stable machine output, fetch paginated results, and handle documented exit codes.
  </Card>
</CardGroup>