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 | shIt 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 whoamiThe 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.