CLI Reference

The StackBlaze CLI gives you full control over your services from the terminal, deploy, tail logs, manage env vars, and more.

Installation

The CLI is distributed as an npm package. It requires Node.js 18 or later.

terminal

npm install -g @stackblaze/cli

Alternatively, install with Homebrew (macOS / Linux):

terminal

brew install stackblaze/tap/stackblaze

Or download a standalone binary for your platform from the CLI Reference.

Authentication

terminal

stackblaze login

This opens your browser and redirects you through the StackBlaze OAuth flow. On success, an API token is saved to ~/.stackblaze/credentials. The token is scoped to your user account and expires after 30 days (refreshed automatically on each CLI use).

terminal

# Authenticate with an API key (for CI environments)
stackblaze login --token sb_prod_your_api_key_here

Tip

For CI/CD pipelines, use an API key from Project Settings → API Keys rather than your personal token. API keys can be scoped to specific permissions and revoked independently.

Project context

Most CLI commands operate on a specific project and service. The CLI infers context from a .stackblaze/config file in your project root. Link a directory to a service with:

terminal

stackblaze link --project acme-app --service api

After linking, you can run stackblaze deploy without specifying the project and service every time.

Command reference

stackblaze deploy

Trigger a new deploy from the current branch's HEAD.

terminal

stackblaze deploy [--service <name>] [--project <name>] [--image <image>]

# Examples
stackblaze deploy
stackblaze deploy --service api --project acme-app
stackblaze deploy --image ghcr.io/my-org/my-app:1.2.3

Flag	Default	Description
`--service, -s`	(from .stackblaze/config)	Service to deploy
`--project, -p`	(from .stackblaze/config)	Project containing the service
`--image`	(builds from source)	Deploy a pre-built Docker image
`--wait`	false	Wait for deploy to complete before exiting
`--env`	production	Target environment (production or preview)

stackblaze logs

Fetch and stream log output from a running service.

terminal

stackblaze logs [--service <name>] [--tail] [--since <duration>]

# Examples
stackblaze logs                          # last 100 lines
stackblaze logs --tail                   # stream live logs
stackblaze logs --since 1h               # logs from the past hour
stackblaze logs --service worker --tail  # live logs for the worker service

Flag	Default	Description
`--tail, -f`	false	Stream logs continuously
`--lines, -n`	100	Number of historical lines to show
`--since`		Show logs since duration (e.g. 30m, 2h, 1d)
`--replica`	(all)	Stream logs from a specific pod replica

stackblaze env

Manage environment variables for a service.

terminal

# List all environment variables
stackblaze env list

# Set one or more variables (triggers redeploy)
stackblaze env set NODE_ENV=production LOG_LEVEL=info

# Set from a .env file
stackblaze env set --from-file .env.production

# Remove a variable
stackblaze env unset LOG_LEVEL

# Show a single variable's value
stackblaze env get DATABASE_URL

Note

Setting or unsetting environment variables triggers an automatic redeploy if the service is currently running. Pass --no-restart to update the value without restarting.

stackblaze ps

Show the running status of all services in the current project.

terminal

stackblaze ps

# Output:
NAME        TYPE    STATUS     REPLICAS   LAST DEPLOY
api         web     running    2/2        5 minutes ago
worker      worker  running    1/1        5 minutes ago
scheduler   cron    idle      ,          2 hours ago

stackblaze rollback

Roll back a service to a previous deployment.

terminal

# List recent deployments
stackblaze deployments list

# Roll back to a specific deployment
stackblaze rollback --deployment dep_abc123

# Roll back to the previous deployment (shorthand)
stackblaze rollback

stackblaze scale

Adjust the number of replicas for a service.

terminal

stackblaze scale api --replicas 4

stackblaze open

Open the service's public URL in your default browser.

terminal

stackblaze open
stackblaze open --service api

stackblaze cron

Manage and trigger cron jobs.

terminal

# List cron runs
stackblaze cron runs

# Trigger an immediate run
stackblaze cron run nightly-report

# View logs for the last run
stackblaze cron logs nightly-report

stackblaze up

Apply a Blueprint (stackblaze.yaml) to your project.

terminal

stackblaze up                  # preview diff and confirm
stackblaze up --dry-run        # preview only, no changes
stackblaze up --yes            # apply without confirmation
stackblaze up --file infra.yaml

Full command summary

Command	Description
`stackblaze login`	Authenticate with StackBlaze
`stackblaze logout`	Remove stored credentials
`stackblaze link`	Link current directory to a service
`stackblaze deploy`	Trigger a new deploy
`stackblaze logs`	View or stream service logs
`stackblaze env set`	Set environment variables
`stackblaze env list`	List environment variables
`stackblaze env unset`	Remove an environment variable
`stackblaze ps`	Show service status
`stackblaze scale`	Change replica count
`stackblaze rollback`	Roll back to a previous deploy
`stackblaze open`	Open service URL in browser
`stackblaze cron run`	Trigger a cron job immediately
`stackblaze up`	Apply a Blueprint file
`stackblaze repos list`	List connected GitHub repos
`stackblaze import compose`	Import from docker-compose.yml

Shell completion

terminal

# bash
stackblaze completion bash >> ~/.bashrc

# zsh
stackblaze completion zsh >> ~/.zshrc

# fish
stackblaze completion fish > ~/.config/fish/completions/stackblaze.fish

CI/CD usage

Use the CLI in your CI pipeline to deploy after a successful test run:

.github/workflows/deploy.yml

name: Deploy to StackBlaze

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install StackBlaze CLI
        run: npm install -g @stackblaze/cli

      - name: Deploy
        run: stackblaze deploy --wait
        env:
          STACKBLAZE_TOKEN: ${{ secrets.STACKBLAZE_TOKEN }}

Generate STACKBLAZE_TOKEN from Project Settings → API Keys and store it as a GitHub Actions secret.