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 right 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 extra 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 built for both people and automation. Every command supports the --format=json flag for machine-readable output, along with --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 up to date automatically.

Authentication

You have two main options for authentication:

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 with the STACKHERO_TOKEN environment variable.

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

When STACKHERO_TOKEN is set, it takes precedence over interactive sessions, so a browser is optional. This approach works 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): Shows readable tables and text for interactive use.
• json: Returns machine-readable JSON, which is helpful for scripts and AI agents.
• script: Returns only raw value(s), which makes it easy to assign output to shell variables.

For example:

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

Commands overview

If you want to see the full list of available commands, you can run stackhero --help. If you want details for 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 that shows how you can 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 up to date automatically. If you ever want to force an update manually, you can run:

stackhero self-update

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