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 designed to help you manage your stacks and services effortlessly. With it, you can create and delete services, access credentials, update configurations, and much more, all from your terminal. The CLI is compatible with Linux (glibc and musl), macOS, and Windows, and comes as a single binary with no dependencies, making installation and updates easy.

Whether you are working interactively or automating workflows with scripts, CI pipelines, or AI agents, the Stackhero CLI is built for both humans and automation. Every command supports the --format=json flag for machine-readable output, as well as --format=script for capturing 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 takes care of keeping itself up to date automatically.

Authentication

You have two main options for authentication:

Interactive (browser-based login)

stackhero login

When you run this command, you will receive a URL (which also automatically opens 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 never need to enter your password into the CLI.

Non-interactive (for scripts, CI, and automation)

For automated workflows, you can create an access token in your dashboard (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 precedence over interactive sessions, so no browser is needed. This is the recommended approach for non-interactive use cases. You can view and revoke tokens from your dashboard at any time.

Output formats

Every command in the CLI accepts a global --format option:

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

For example:

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

Commands overview

If you are looking for a full list of available commands, you can run stackhero --help. For detailed information on a specific command, 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 demonstrates 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"

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # You can find this with: stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # You can find this with: stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # You can find this with: stackhero regions-list

# Create a stack
stackId=$(stackhero --format=script stack-create \
  --organization-id="${organizationId}" \
  --name="My stack")
echo "Stack: ${stackId}"

# Add a service
serviceId=$(stackhero --format=script service-add \
  --stack-id="${stackId}" \
  --service-store-id="${serviceStoreId}" \
  --instance-store-id="${instanceStoreId}" \
  --region-id="${regionId}")
echo "Service: ${serviceId}"

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

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

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

Updating and uninstalling

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

stackhero self-update

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