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

# Install and update the StackShift CLI

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

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

## Goal

Install a release through a supported channel and verify the resulting executable.

## Prerequisites

* Homebrew on macOS, Scoop on Windows, or `cosign` for the signed release installers
* An amd64 or arm64 system running macOS, Linux, or Windows

## Workflow

<Steps>
  <Step>
    Choose the package channel for your operating system.
  </Step>

  <Step>
    Install the CLI without bypassing signature or checksum verification.
  </Step>

  <Step>
    Run `stackshift version` to confirm the installed build.
  </Step>

  <Step>
    Use the same package manager, or the verified self-updater, for future releases.
  </Step>
</Steps>

## Homebrew on macOS

The public StackShift tap installs a formula from the signed release source archive. Homebrew installs its Go build dependency automatically.

```bash theme={null}
brew install stackshiftCloud/tap/stackshift
```

## Scoop on Windows

```powershell theme={null}
scoop bucket add stackshift https://github.com/stackshiftCloud/scoop-bucket
scoop install stackshift
```

## Signed installer on macOS or Linux

The installer requires an exact release tag and `cosign`. It verifies the Sigstore bundle for `checksums.txt`, then verifies the selected archive SHA-256 digest.

```bash theme={null}
VERSION=v1.0.2
BASE=https://github.com/stackshiftCloud/stackshift-cli/releases/download/$VERSION
curl -fsSLO "$BASE/install-cli.sh"
chmod 0755 install-cli.sh
STACKSHIFT_CLI_VERSION="$VERSION" ./install-cli.sh
```

## Signed installer on Windows

```powershell theme={null}
$Version = "v1.0.2"
$Base = "https://github.com/stackshiftCloud/stackshift-cli/releases/download/$Version"
Invoke-WebRequest "$Base/install-cli.ps1" -OutFile install-cli.ps1
$env:STACKSHIFT_CLI_VERSION = $Version
.\install-cli.ps1
```

## Check and apply updates

The self-updater supports macOS, Linux, and Windows on amd64 and arm64. It requires `cosign`, verifies the release workflow identity and checksum, and requires `--yes` before replacing the current executable.

```bash theme={null}
stackshift update --check
stackshift update --yes
stackshift update --version v1.0.2 --yes
```

## Expected result

<Check>
  `stackshift version` prints the release version, commit, and build date for your platform.
</Check>

## Common failures

<Warning>
  * `cosign` is missing when using an installer or self-update.
  * The requested version is not an exact `vMAJOR.MINOR.PATCH` release tag.
  * The current executable is in a location the user cannot replace.
  * A package-manager shell has not refreshed `PATH` after installation.
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="StackShift CLI overview" href="/cli/overview">
    Install the CLI, authenticate securely, select a project, and run the first customer API workflow.
  </Card>

  <Card title="Diagnostics, completion, and troubleshooting" href="/cli/diagnostics-and-troubleshooting">
    Check version compatibility, produce sanitized diagnostics, install completion, and resolve common failures.
  </Card>
</CardGroup>