Start here

The stackd CLI

stackd, for Linux and macOS, deploys apps, sets their variables, follows their logs, runs one-off commands and opens shells, from your machine or CI, with an API token.

Installing

curl -fsSL https://get.stackd.sh/cli.sh | sh

It downloads the release's binary for the machine (x86_64 or aarch64, Linux or macOS), checks it against the release's SHA256SUMS, and installs it in /usr/local/bin when that's writable, else ~/.local/bin. On a server running the panel /usr/local/bin/stackd is the panel itself, so it goes in ~/.local/bin there. --version vX.Y.Z and --dir choose.

Upgrading

stackd upgrade replaces the binary that's running, in its place, with the latest release, checked against SHA256SUMS, or with --version vX.Y.Z (older ones too, while they're still published). stackd upgrade --check only says whether a newer one is out. It never goes back to an older version on its own. In a directory you can't write to, run it with sudo.

Signing in

Make a token in the panel (Settings → API tokens, see Roles and projects), then:

stackd login https://panel.example.com        # pastes the token from stdin
stackd login https://panel.example.com --with-token stk_…
stackd whoami

The URL and token are kept in ~/.config/stackd/config.json (mode 0600; $XDG_CONFIG_HOME is honoured). --api and --token, or STACKD_API and STACKD_TOKEN, win over it: CI sets those and never logs in. stackd logout forgets them.

Commands

Apps and databases are named by name or id.

Command What it does
stackd apps list, apps show web Apps; one's settings, domains and replicas
stackd deploy web [--image repo:tag] [--no-wait] Deploys, waiting until the replicas are up (exit 1 if one fails)
stackd apps restart web Restarts its running replicas
stackd apps rollback web [--batch id] Back to the image before the newest deploy (or that one)
stackd env list web [--reveal] Variables' names, or names and values
stackd env get web KEY One value
stackd env set web K=V … [--deploy], env unset web K … [--deploy] Change variables; they apply at the next deploy, or now with --deploy
stackd logs web [-n 100] [-s text] Kept lines, newest last, optionally only those containing text
stackd logs web -f Follows every running replica live, each line prefixed with its server
stackd builds list web, builds show id, builds cancel id Builds of an app built from a repo
stackd builds start web [--commit sha] [--no-deploy] [--no-wait] Builds and deploys, printing the build's output as it goes
stackd run web -- php artisan migrate A one-off command in a new container of the app; its output, and its exit code as the CLI's
stackd shell web [--replica server-or-id] A terminal in a running replica (the web process's by default)
stackd databases list, databases show db Databases and stores, and how apps reach them
stackd servers list, servers add name Servers; the command that installs a new one
stackd canary start|status|promote|abort web A canary release (Canary releases)
stackd promote web-staging web The image one app runs, deployed to another (Approvals)
stackd approvals list|approve|reject, apps protect web on Protected apps' deploy requests (Approvals)
stackd apps maintenance web on|off [--allow …] Maintenance mode (Maintenance)
stackd apps sleep web 30|off Sleep after 30 idle minutes (Sleep)
stackd apply [-f stackd.toml] [--dry-run] [--prune] [--deploy] Makes apps match a stackd.toml (Apps as code)
stackd export web … Prints apps as a stackd.toml
stackd upgrade [--version vX.Y.Z] [--check] Replaces the CLI with the latest release, or that one

--json prints the API's JSON instead of a table, for scripts.

In CI

A deploy token (Roles and projects) can deploy, build, restart and roll back, and nothing else:

- run: curl -fsSL https://get.stackd.sh/cli.sh | sh
- run: stackd deploy web --image ghcr.io/acme/web:${{ github.sha }}
  env:
    STACKD_API: https://panel.example.com
    STACKD_TOKEN: ${{ secrets.STACKD_TOKEN }}

stackd deploy exits 1 when a replica fails to start, so the job fails with it. While a panel with several replicas changes leader (an update, a failover), its API answers standby for a few seconds. Commands wait and try again for up to a minute, so a deploy then doesn't fail the job.