Use the CLI

Install and use the Stackhero CLI to manage your stacks and services from the command line, scripts, CI, and AI agents

Introduction

The Stackhero CLI is a lightweight, self-contained command-line tool that helps you manage your stacks and services directly from your terminal. You can use it to create and delete services, access credentials, update configurations, and handle many other everyday tasks.

The CLI works on Linux (glibc and musl), macOS, and Windows. It ships as a single binary with no additional dependencies, which makes installation and updates simple.

Whether you are working interactively or automating workflows with scripts, CI pipelines, or AI agents, the Stackhero CLI is designed for both users and automation. Every command supports the --format=json option for machine-readable output, as well as --format=script when you want to capture raw values in shell variables.

Installation

You can install the latest version by running:

curl -fsSL https://www.stackhero.io/install.sh | sh

This command downloads the correct binary for your platform and installs it as stackhero. The CLI also keeps itself automatically up to date.

Authentication

You have two main authentication options:

Interactive browser-based login

stackhero login

When you run this command, the CLI gives you a URL and also opens it automatically in your browser. From there, you can approve access directly from your Stackhero dashboard, where you are already signed in.

Two-factor authentication is fully supported, and you do not need to enter your password in the CLI.

Non-interactive authentication for scripts, CI, and automation

For automated workflows, you can create an access token in your dashboard under Account > Access tokens and provide it to the CLI using the STACKHERO_TOKEN environment variable.

export STACKHERO_TOKEN="usr-xxxxxx:your-token"
stackhero organizations-list

When STACKHERO_TOKEN is set, it takes priority over interactive sessions, so using a browser becomes optional. This approach works very well for non-interactive use cases. You can review and revoke tokens from your dashboard at any time.

Output formats

Every CLI command accepts a global --format option:

• human (default): Displays readable tables and text for interactive use.
• json: Returns machine-readable JSON, which is useful for scripts and AI agents.
• script: Returns only raw value(s), which makes it easy to assign the output to shell variables.

For example:

stackhero organizations-list --format=json
stackId=$(stackhero --format=script stack-create --name="My stack")

Command overview

If you want to see the full list of available commands, you can run stackhero --help. If you want details about a specific command, you can try stackhero COMMAND --help.

Some commonly used commands include:

• Organizations: organizations-list
• Stacks: stacks-list, stack-create, stack-rename, stack-delete
• Services: services-list, service-add, service-wait-for, service-rename, service-delete
• Configuration: service-configuration-get, service-configuration-set, service-configuration-example
• Store: services-store-list, instances-store-list, regions-list
• Upgrades: service-upgrade-instances-store-list, service-upgrade-instance
• Account: login, logout
• Maintenance: self-update

Example: Create a service end to end

Here is a sample script showing how to create a stack, add a service, wait for it to be ready, and retrieve its credentials. This example is fully non-interactive and uses the STACKHERO_TOKEN environment variable.

#!/bin/bash
set -e

export STACKHERO_TOKEN="usr-xxxxxx:your-token"

serviceStore="directus"   # A service store name. See: `stackhero services-store-list`
instance="1GB"            # An instance (size) name. See: `stackhero instances-store-list --service-store=directus`
region="europe"           # A region name. See: `stackhero regions-list`

# Create a stack (uses your only organization, add `--organization` if you have several)
stackId=$(stackhero --format=script stack-create \
  --name="My stack")
echo "Stack: ${stackId}"

# Add a service (names are resolved automatically, and the stack ID above also works)
serviceId=$(stackhero --format=script service-add \
  --stack="My stack" \
  --service-store="${serviceStore}" \
  --instance="${instance}" \
  --region="${region}")
echo "Service: ${serviceId}"

# Wait for the service to be running
stackhero service-wait-for --service="${serviceId}"

# Retrieve credentials and configuration
stackhero service-configuration-get --service="${serviceId}" --format=json

Each service documentation page includes a ready-to-run Automate with the CLI guide tailored to that service, so you have everything you need to get started.

Updating and uninstalling

The CLI keeps itself automatically up to date. If you ever want to force a manual update, you can run:

stackhero self-update

If you want to uninstall the CLI, you can simply delete the stackhero binary from your system.