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, standalone command-line tool designed to enable you to manage your stacks and services with ease. With this tool, you can create and delete services, access credentials, update configurations, and much more, all directly from your terminal. The CLI is compatible with Linux (glibc and musl), macOS, and Windows, and is provided as a single binary with no dependencies, making both installation and updates straightforward.

Whether you are working interactively or automating your 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 for capturing raw values into shell variables.

Installation

You can install the latest version by running:

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

This command downloads the appropriate 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 be provided with a URL (which also opens automatically in your browser). You can then 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 via 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 required. This is the recommended method for non-interactive use cases. You can view and revoke your tokens from your dashboard at any time.

Output formats

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

• human (default): Displays readable tables and text for interactive use.
• json: Produces machine-readable JSON, ideal for scripts and AI agents.
• script: Returns only the 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

To get the full list of available commands, run stackhero --help. For detailed information on a specific command, use 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 an example script that demonstrates 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"

organizationId="org-xxxxxx"
serviceStoreId="svs-xxxxxx"   # You can list with: stackhero services-store-list --organization-id=org-xxxxxx
instanceStoreId="ist-xxxxxx"  # You can list with: stackhero instances-store-list --organization-id=org-xxxxxx --service-store-id=svs-xxxxxx
regionId="europe"             # You can list 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 operational
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-use "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 wish to manually force an update, you can run:

stackhero self-update

To uninstall the CLI, simply delete the stackhero binary from your system.