CLI Command Reference

Complete reference for the Hyperstack CLI (hs).

Global Options

Option	Description
`--config, -c <path>`	Path to hyperstack.toml (default: `hyperstack.toml`)
`--json`	Output as JSON
`--verbose`	Enable verbose output
`--help, -h`	Show help
`--version, -V`	Show version
`--completions <SHELL>`	Generate shell completions (bash, zsh, fish, powershell, elvish)

Quick Reference

Command	Description
`hyperstack-cli create [name]`	Scaffold a new app from a template
`hs init`	Initialize a stack project
`hs up [stack]`	Deploy stack (push + build + deploy)
`hs push [stack]`	Push stack to remote (alias)
`hs status`	Show project overview
`hs stack list`	List all stacks
`hs stack show`	Show stack details
`hs telemetry status`	Show telemetry status
`hs explore`	Discover stacks and schemas

Create a New App

hyperstack-cli create [name]

Scaffold a new Hyperstack project from a template. This is the fastest way to get started.

# Interactive — prompts for name and template
npx hyperstack-cli create

# With project name
npx hyperstack-cli create my-app

# With specific template
npx hyperstack-cli create my-app --template react-ore

Available templates:

Template	Aliases	Description
`react-ore`	`ore-react`	ORE mining rounds viewer (React + Vite)
`rust-ore`	`ore-rust`	ORE mining rounds client (Rust + Tokio)
`typescript-ore`	`ore-typescript`, `ts-ore`, `ore-ts`	ORE mining rounds client (TypeScript CLI)

Options:

Flag	Description
`--template <name>`	Skip interactive selection
`--offline`	Use cached templates only
`--force-refresh`	Clear template cache and re-download
`--skip-install`	Don’t run `npm install` automatically

Templates are downloaded from GitHub releases and cached in ~/.hyperstack/templates/.

Project Setup

hs init

Initialize a new Hyperstack project.

hs init

Creates hyperstack.toml with auto-discovered stacks from .hyperstack/*.stack.json.

hs config validate

Validate your configuration.

hs config validate

Authentication

Hyperstack is currently in closed beta. Contact us to receive an API key.

Save your API key to authenticate.

# Interactive — prompts for API key
hs auth login

# Or pass directly
hs auth login --key <your-api-key>

Options:

Flag	Description
`--key, -k`	API key (prompts if not provided)

hs auth logout

Remove stored credentials.

hs auth logout

hs auth status

Check local authentication status.

hs auth status

hs auth whoami

Verify authentication with server.

hs auth whoami

Credentials location: ~/.hyperstack/credentials.toml

Schema Discovery

hs explore

Discover available stacks and explore their schemas. Works without authentication for public stacks.

# List all available stacks
hs explore

# Show entities and views for a stack
hs explore ore

# Show fields and types for a specific entity
hs explore ore OreRound

# JSON output (for agents and scripts)
hs explore --json
hs explore ore --json
hs explore ore OreRound --json

Arguments:

Argument	Description
`[name]`	Stack name to explore
`[entity]`	Entity name to show field details

Output varies by specificity:

Command	Shows
`hs explore`	All available stacks with entity names
`hs explore <stack>`	Stack entities, views, and field counts
`hs explore <stack> <entity>`	Entity fields with types, sections, and views

Public stacks are visible without authentication. Log in with hs auth login to also see global stacks and your own deployed stacks.

Deployment

hs up [stack-name]

Deploy a stack: push, build, and deploy in one command.

# Deploy all stacks
hs up

# Deploy specific stack
hs up my-stack

# Deploy to branch
hs up my-stack --branch staging
# Creates: my-stack-staging.stack.usehyperstack.com

# Preview deployment
hs up my-stack --preview

# Preview what would be deployed (no actual deployment)
hs up my-stack --dry-run

Options:

Flag	Description
`--branch, -b <name>`	Deploy to named branch
`--preview`	Create preview deployment
`--dry-run`	Show what would be deployed without deploying

hs status

Show overview of all stacks, builds, and deployments.

hs status
hs status --json

Stack Management

hs stack list

List all stacks with their deployment status.

hs stack list
hs stack list --json

Output:

STACK              STATUS     VERSION  URL
settlement-game    active     v3       wss://settlement-game.stack.usehyperstack.com
token-tracker      active     v1       wss://token-tracker.stack.usehyperstack.com

hs stack push [stack-name]

Push local stacks to remote.

# Push all stacks
hs stack push

# Push specific stack
hs stack push my-stack

hs stack show <stack-name>

Show detailed stack information including deployment status and versions.

hs stack show my-stack
hs stack show my-stack --version 3
hs stack show my-stack -v 3

Options:

Flag	Description
`--version, -v <n>`	Show specific version details

Output includes:

Entity information
Deployment status and URL
Latest version details
Recent builds

hs stack versions <stack-name>

Show version history.

hs stack versions my-stack
hs stack versions my-stack --limit 10
hs stack versions my-stack -l 10

Options:

Flag	Description
`--limit, -l <n>`	Maximum number of versions (default: 20)

hs stack delete <stack-name>

Delete a stack from remote.

hs stack delete my-stack
hs stack delete my-stack --force  # Skip confirmation
hs stack delete my-stack -f

Options:

Flag	Description
`--force, -f`	Skip confirmation prompt

hs stack rollback <stack-name>

Rollback to a previous deployment.

# Rollback to previous version
hs stack rollback my-stack

# Rollback to specific version
hs stack rollback my-stack --to 2

# Rollback to specific build
hs stack rollback my-stack --build 123

# Rollback branch deployment
hs stack rollback my-stack --branch staging

Options:

Flag	Description
`--to <version>`	Target version
`--build <id>`	Target build ID
`--branch <name>`	Branch to rollback (default: production)
`--rebuild`	Force full rebuild
`--no-wait`	Don’t watch progress

hs stack stop <stack-name>

Stop a deployment.

hs stack stop my-stack
hs stack stop my-stack --branch staging
hs stack stop my-stack --force  # Skip confirmation

Options:

Flag	Description
`--branch <name>`	Branch deployment to stop
`--force, -f`	Skip confirmation prompt

SDK Generation

hs sdk list

List stacks available for SDK generation.

hs sdk list

hs sdk create typescript <stack-name>

Generate TypeScript SDK.

hs sdk create typescript my-stack
hs sdk create typescript my-stack --output ./src/generated/
hs sdk create typescript my-stack --package-name @myorg/my-sdk
hs sdk create typescript my-stack --url wss://my-stack.stack.usehyperstack.com

Options:

Flag	Description
`--output, -o <path>`	Output file path (overrides config)
`--package-name, -p <name>`	Package name for TypeScript
`--url <url>`	WebSocket URL for the stack

hs sdk create rust <stack-name>

Generate Rust SDK crate.

hs sdk create rust my-stack
hs sdk create rust my-stack --output ./crates/
hs sdk create rust my-stack --crate-name my-stack-sdk
hs sdk create rust my-stack --module  # Generate as module instead of crate
hs sdk create rust my-stack --url wss://my-stack.stack.usehyperstack.com

Options:

Flag	Description
`--output, -o <path>`	Output directory path (overrides config)
`--crate-name <name>`	Custom crate name for generated Rust crate
`--module`	Generate as a module (mod.rs) instead of a standalone crate
`--url <url>`	WebSocket URL for the stack

The --module flag generates the SDK as a Rust module (with mod.rs) that can be embedded directly into an existing crate, rather than creating a standalone crate with its own Cargo.toml. This is useful for monorepo setups or when you want to include generated code within your own crate.

Configuration File

File: hyperstack.toml

[project]
name = "my-project"

# SDK generation settings
[sdk]
output_dir = "./generated"                              # Default output for both languages
typescript_output_dir = "./frontend/src/generated"     # Override for TypeScript only
rust_output_dir = "./crates/generated"                 # Override for Rust only
typescript_package = "@myorg/my-sdk"                   # Package name for TypeScript
rust_module_mode = false                               # Generate Rust SDKs as modules by default

# Build preferences
[build]
watch_by_default = true

# Stack definitions
# Auto-discovered from .hyperstack/*.stack.json
# Define explicitly for custom naming or per-stack overrides:
[[stacks]]
name = "my-game"
stack = "SettlementGame"                               # Stack name or path to .stack.json
description = "Settlement game tracking"
typescript_output_file = "./src/generated/game.ts"    # Per-stack TypeScript output path
rust_output_crate = "./crates/game-stack"             # Per-stack Rust output path
rust_module = true                                     # Per-stack: generate as module instead of crate

SDK Configuration Options

Option	Scope	Description
`output_dir`	`[sdk]`	Default output directory for both languages
`typescript_output_dir`	`[sdk]`	Override output directory for TypeScript SDKs
`rust_output_dir`	`[sdk]`	Override output directory for Rust SDKs
`typescript_package`	`[sdk]`	Package name for generated TypeScript code
`rust_module_mode`	`[sdk]`	Generate Rust SDKs as modules by default
`typescript_output_file`	`[[stacks]]`	Per-stack TypeScript output file path
`rust_output_crate`	`[[stacks]]`	Per-stack Rust output crate/module directory
`rust_module`	`[[stacks]]`	Per-stack override for module vs crate generation

For most projects, you only need:

[project]
name = "my-project"

The CLI auto-discovers stacks from .hyperstack/*.stack.json files.

Build Process

Status Flow

pending → uploading → queued → building → pushing → deploying → completed
                                                              ↘ failed

Build Phases

Phase	Description
SUBMITTED	Queued for processing
PROVISIONING	Starting build environment
DOWNLOAD_SOURCE	Preparing source
INSTALL	Installing dependencies
PRE_BUILD	Preparing build
BUILD	Compiling
POST_BUILD	Finalizing
UPLOAD_ARTIFACTS	Publishing image
FINALIZING	Deploying to runtime

Typical Workflows

First-Time Setup

# Initialize project
hs init

# Login with your API key
hs auth login

# Validate configuration
hs config validate

Development Cycle

# Make changes to stack, rebuild Rust crate
cargo build

# Deploy
hs up my-stack

# Check status
hs status

Branch Deploys

# Deploy feature branch
hs up my-stack --branch feature-x
# URL: my-stack-feature-x.stack.usehyperstack.com

# Check deployment
hs stack list

# Clean up when done
hs stack stop my-stack --branch feature-x

Rollback

# Quick rollback to previous version
hs stack rollback my-stack

# Rollback to specific version
hs stack rollback my-stack --to 2

Telemetry

Hyperstack collects anonymous usage data to improve the CLI. No personal information or project details are sent.

hs telemetry status

Show current telemetry status.

hs telemetry status

hs telemetry enable

Enable telemetry collection.

hs telemetry enable

hs telemetry disable

Disable telemetry collection.

hs telemetry disable

Environment Variables

Variable	Description
`HYPERSTACK_API_URL`	Override API endpoint
`DO_NOT_TRACK=1`	Disable telemetry (standard)
`HYPERSTACK_TELEMETRY_DISABLED=1`	Disable telemetry (Hyperstack-specific)

Error Reference

Error	Solution
`Not authenticated`	Run `hs auth login`
`Stack not found`	Check `hs stack list` for available stacks
`Stack file not found`	Run `cargo build` to generate stack spec
`Build failed`	Try again
`Config invalid`	Run `hs config validate`

WebSocket URL Patterns

After successful deployment:

Type	Pattern
Production	`wss://{stack-name}.stack.usehyperstack.com`
Branch	`wss://{stack-name}-{branch}.stack.usehyperstack.com`
Local	`ws://localhost:8080`

Get the URL with:

hs stack show <stack-name>