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

# StackShift CLI overview

> Install the CLI, authenticate securely, select a project, and run the first customer API workflow.

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

## Goal

Get from a new installation to an authenticated, verified CLI session.

## Prerequisites

* A StackShift account
* A supported macOS, Linux, or Windows system

## Workflow

<Steps>
  <Step>
    Install the current signed CLI release.
  </Step>

  <Step>
    Run browser authorization for the default profile.
  </Step>

  <Step>
    Verify the active identity and server compatibility.
  </Step>

  <Step>
    List projects and optionally save a default project.
  </Step>
</Steps>

## What the CLI is

The StackShift CLI is a native Go client for existing customer-facing StackShift APIs. It does not collect telemetry and uses `https://api.stackshift.cloud` as its only built-in production API default.

Commands cover purpose-built workflows such as login, manifests, deployments, logs, remote execution, environment variables, updates, and diagnostics. Resource namespaces expose the customer API operations already implemented by StackShift.

## First session

* `auth login` opens the device authorization page and waits for approval.
* `auth status` shows the active profile, API URL, user name, and email.
* `doctor` checks the profile, API, minimum CLI version, and authentication.
* `project list` uses table output by default; add `-o json` for automation.

```bash theme={null}
stackshift version
stackshift auth login
stackshift auth status
stackshift doctor
stackshift project list
```

## Save a default project

A project argument can be a UUID, an exact case-insensitive name, or a slug. Saving a default lets project-scoped commands omit the positional project.

```bash theme={null}
stackshift context set default --project my-api --environment production
stackshift logs --lines 50
stackshift deploy --ref main
```

## Customer boundary

The CLI is limited to customer product paths. Its raw API command rejects admin, internal, agent, webhook-ingestion, portal, and compute-runner routes.

## Expected result

<Check>
  The CLI identifies your StackShift account and can read customer resources from the production API.
</Check>

## Common failures

<Warning>
  * `stackshift` is not on `PATH` after installation.
  * Browser authorization expired before approval.
  * The selected profile has no credential in the operating-system credential manager.
  * A saved project name is missing or ambiguous.
</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="Profiles, defaults, and global options" href="/cli/profiles-and-global-options">
    Use profiles for API and resource defaults, then override them explicitly for one command.
  </Card>
</CardGroup>