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

​
Goal

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

​
Prerequisites

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

​
Workflow

1
Install the current signed CLI release.
2
Run browser authorization for the default profile.
3
Verify the active identity and server compatibility.
4
List projects and optionally save a default project.

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

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

​
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

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

​
Common failures

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

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.

Profiles, defaults, and global options

Use profiles for API and resource defaults, then override them explicitly for one command.