Skip to content

Latest commit

 

History

History
441 lines (299 loc) · 7.35 KB

commands.mdx

File metadata and controls

441 lines (299 loc) · 7.35 KB

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
--completions <shell> Generate shell completions (bash, zsh, fish, powershell, elvish)
--help, -h Show help
--version, -V Show version

Quick Reference

Command Description
hs init Initialize project
hs up [stack] Deploy stack (push + build + deploy)
hs status Show project overview
hs auth login Authenticate

Project Setup

hs init

Initialize a new Hyperstack project.

hs init

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

hs config validate

Validate your configuration.

hs config validate

Authentication

hs auth register

Create a new account.

hs auth register

Prompts for username and password (min 8 characters).

hs auth login

Login to your account.

hs auth login

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

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

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 deployment status.

hs stack list
hs stack list --json

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

Show detailed stack information including deployment status and recent builds.

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

hs stack versions

Show version history.

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

hs stack delete

Delete a stack from remote.

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

hs stack rollback

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
--rebuild, -r Force full rebuild
--no-wait, -n Don't watch progress

hs stack stop

Stop a running deployment.

hs stack stop my-stack
hs stack stop my-stack --branch staging

Build Commands (Power User)

These commands are for advanced users who need fine-grained control over the build process.

hs build create

Create a new build from a stack.

hs build create my-stack
hs build create my-stack --version 2
hs build create my-stack --ast-file ./my-stack.ast.json
hs build create my-stack --no-wait

Options:

Flag Description
--version, -v <n> Use specific version (default: latest)
--ast-file <path> Use local AST file directly
--no-wait, -n Don't wait for completion

hs build list

List all builds.

hs build list
hs build list --status completed
hs build list --limit 10

hs build status

Get detailed build status.

hs build status 123
hs build status 123 --watch
hs build status 123 --json

SDK Generation

hs sdk list

List stacks available for SDK generation.

hs sdk list

hs sdk create typescript

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

Configuration File

File: hyperstack.toml

[project]
name = "my-project"

# SDK generation settings
[sdk]
output_dir = "./generated"
typescript_package = "@myorg/my-sdk"

# Build preferences
[build]
watch_by_default = true

# Stack definitions
# Auto-discovered from .hyperstack/*.ast.json
# Define explicitly for custom naming:
[[stacks]]
name = "my-game"
ast = "SettlementGame"  # Entity name or path to .ast.json
description = "Settlement game tracking"

[[stacks]]
name = "token-tracker"
ast = ".hyperstack/Token.ast.json"

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

# Create account and login
hs auth register

# Validate configuration
hs config validate

Development Cycle

# Make changes, 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

Environment Variables

Variable Description
HYPERSTACK_API_URL Override API endpoint

Error Reference

Error Solution
Not authenticated Run hs auth login
Stack not found Check hs stack list for available stacks
AST file not found Run cargo build to generate AST
Build failed Check hs build status <id> for details
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

Get the URL with:

hs stack show <stack-name>