CLI

Every command prints its own help: stackblaze --help, stackblaze <command> --help and stackblaze <command> <subcommand> --help. The command reference below covers every command, flag and example.

Install

The installers download a standalone binary. No Node.js is needed, and there is no npm package.

curl -fsSL https://stackblaze.com/install.sh | sh

irm https://stackblaze.com/install.ps1 | iex

brew tap stackblaze/tap && brew install stackblaze

On Linux and macOS the binary goes to ~/.local/bin (or /usr/local/bin when run as root); on Windows to %LOCALAPPDATA%\StackBlaze\bin, which is added to your user PATH. If Homebrew refuses to load the formula from an untrusted tap, run brew trust --tap stackblaze/tap once and install again.

Update with stackblaze upgrade, or brew upgrade stackblaze for a Homebrew install. See upgrade.

Authenticate

stackblaze login

login prints a one-click URL and a code, opens your browser, and waits until you approve. The token is saved to ~/.config/stackblaze/config.json on macOS and Linux (under $XDG_CONFIG_HOME/stackblaze when that is set) and to %APPDATA%\StackBlaze\config.json on Windows, with mode 600; override the path with STACKBLAZE_CONFIG. On a server or over SSH, use stackblaze login --browserless. With an API token, use stackblaze login --token kbr_pat_…; with email and password (2FA supported, terminal only), stackblaze login --password.

Create API tokens in the dashboard under Settings → API tokens. A token belongs to your organization and carries your permissions. In CI, skip login and set both variables; commands read them on every run:

export STACKBLAZE_API_URL=https://api.stackblaze.cloud
export STACKBLAZE_TOKEN=kbr_pat_…
stackblaze whoami

Flags (--token, --api-url) override the environment, which overrides the saved login.

Quick start

stackblaze init     # create a project and link this directory
stackblaze up       # create the app and stream the build
stackblaze logs -f  # follow the app's logs
stackblaze open     # open the app's dashboard page (--app-url opens the app)

In a git checkout with a remote, up builds the remote and current branch, not local files, so push first. In a folder without a git remote (or with --local) it uploads the folder and builds that. Run up again to ship changes. See up.

Scope and common flags

Most commands act on one app, identified by a project, an environment and an app. They are resolved in this order:

1. Flags: -p, --project, -e, --env, -a, --app
2. Environment: STACKBLAZE_PIPELINE, STACKBLAZE_PHASE, STACKBLAZE_APP
3. The nearest .stackblaze/project.json, searching upward from the current directory (written by init, link and up)

The CLI says project and environment, and so do its flags; --pipeline and --phase still work. The variables and the keys in JSON output keep the API's names, pipeline and phase. When the environment is still unknown, app commands use production. Run stackblaze context to see what resolves.

Global options

These work on every command that uses them. --api-url, --token, --org and -y also go before the command name: stackblaze --org acme apps list.

When stdin is not a terminal (CI, pipes, AI agents), the CLI never prompts: a command that would ask fails at once with exit 1 and changes nothing. Pass -y to confirm, or the value as a flag.

Output and exit codes

Results go to stdout. Progress, prompts, warnings and errors go to stderr, so you can pipe a result without catching progress messages. With -o json (or --json), stdout carries only the JSON result:

stackblaze apps list -o json | jq -r '.[].app'

Streaming commands write one JSON record per line (NDJSON) instead: up --ci, builds logs --ci, logs -f --json, cron logs -f --json, metrics --watch --json, and --ci on cron run and addons backups create|restore. Commands that take --wait print one JSON document with --wait --json, with the readiness check under wait; a wait that does not end with the app running exits 1. Interactive commands (ssh, shell, connect, run) and local tooling (setup, completion, upgrade, docs) have no JSON mode. Set NO_COLOR=1 to turn off colour.

A 403 means you are signed in and the request was refused, so it exits 3, not 2. With --json, an error is printed on stderr as one JSON document, {"error":{"message":…,"code":…,"status":…}}, with the same exit codes. Commands that wait (--wait, wait) take --timeout <seconds> (default 600 unless the command says otherwise).

Destructive commands ask for confirmation. Without a terminal the prompt gets no answer and the command exits 1 without changing anything, so pass -y in scripts. stackblaze run exits with the code of the command it runs (127 when the program is not found), and ssh with the code of the remote shell.

Environment variables

CI and GitHub Actions

stackblaze up is safe to re-run, so the same command works on every push: the first run creates the app, later runs update it and build again. With --ci it streams the build as NDJSON, and the job fails when the build fails.

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      STACKBLAZE_API_URL: https://api.stackblaze.cloud
      STACKBLAZE_TOKEN: ${{ secrets.STACKBLAZE_TOKEN }}
      STACKBLAZE_PIPELINE: my-project
      STACKBLAZE_PHASE: production
      STACKBLAZE_APP: web
    steps:
      - uses: actions/checkout@v4
      - name: Install StackBlaze CLI
        run: |
          curl -fsSL https://stackblaze.com/install.sh | sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Deploy
        run: stackblaze up --ci --wait

Keep the actions/checkout step: up reads the repository and branch from the checkout, and builds exactly the pushed commit (the pull request's head commit on pull_request events). The very first build of a brand-new app uses the head of the branch. --wait also waits up to 10 minutes for the new version to be running; drop it to finish when the build succeeds. If the app already auto-deploys on push, you do not need this workflow.

up --ci records

Command reference