hyperstack-cli

Command-line tool for building, deploying, and managing HyperStack stream specifications.

Installation

From Source

# Clone the repository
git clone https://github.com/HyperTekOrg/hyperstack.git
cd hyperstack

# Build and install the CLI
cargo install --path cli

# Or just build (binary will be at target/release/hs)
cargo build --release -p hyperstack-cli

Quick Start

1. Initialize configuration

hs config init

This creates a hyperstack.toml file with example configurations.

2. Authenticate

# Register a new account
hs auth register

# Or login to an existing account
hs auth login

3. Edit hyperstack.toml to configure your specs:

[project]
name = "my-project"

[sdk]
output_dir = "./generated"
typescript_package = "hyperstack-react"  # optional
rust_crate_prefix = "hyperstack"         # optional, prefix for generated crate names

# Specs are auto-discovered from .hyperstack/*.ast.json
# Define explicitly for custom naming:
[[specs]]
name = "settlement-game"      # optional, defaults to kebab-case of entity
ast = "SettlementGame"        # entity name or path to .ast.json
description = "Settlement game state tracking"  # optional

4. Push your spec to the cloud

hs spec push settlement-game

5. Build and deploy

# Create a build from your spec
hs build create settlement-game

# Watch the build progress
hs build status <build-id> --watch

6. Connect to your deployment

# View deployment info including WebSocket URL
hs deploy info <build-id>

Commands

Authentication

hs auth register

Register a new account.

hs auth login

Login to your account.

hs auth logout

Logout and remove stored credentials.

hs auth status

Check if you're authenticated (local check only).

hs auth whoami

Verify your authentication with the server and show account info.

Spec Management

hs spec push [spec-name]

Push local specs with their AST to remote. Reads specs from hyperstack.toml and uploads AST from .hyperstack/<entity>.ast.json.

# Push all specs
hs spec push

# Push specific spec
hs spec push settlement-game

hs spec pull

Pull remote specs to local config.

hs spec list

List all remote specs.

hs spec versions <spec-name>

Show version history for a spec.

hs spec versions settlement-game --limit 10

hs spec show <spec-name>

Show detailed spec information.

# Show spec info with latest version
hs spec show settlement-game

# Show specific version details
hs spec show settlement-game --version 3

hs spec delete <spec-name>

Delete a spec from remote.

# Interactive confirmation
hs spec delete settlement-game

# Skip confirmation
hs spec delete settlement-game --force

Build Commands

hs build create <spec-name>

Create a new build from a spec.

# Build latest version
hs build create settlement-game

# Build specific version
hs build create settlement-game --version 2

# Build from local AST file
hs build create settlement-game --ast-file ./my-spec.ast.json

hs build list

List builds for your account.

# List builds
hs build list

# Filter by status
hs build list --status completed

# Limit results
hs build list --limit 10

hs build status <build-id>

Get detailed build status.

# Show status
hs build status 123

# Watch progress until completion
hs build status 123 --watch

# Output as JSON
hs build status 123 --json

hs build logs <build-id>

View build logs (opens CloudWatch logs URL).

hs build logs 123

Deployment Commands

hs deploy info <build-id>

Show deployment info for a completed build.

hs deploy info 123

Output includes:

• Atom name
• Namespace
• WebSocket URL
• Container image

hs deploy list

List all active deployments.

hs deploy list --limit 20

SDK Generation

hs sdk list

List all available specs from your configuration.

hs sdk create typescript <spec-name>

Generate a TypeScript SDK for the specified spec.

# Generate with default settings
hs sdk create typescript settlement-game

# Generate with custom output path
hs sdk create typescript settlement-game --output ./my-sdk/game.ts

# Generate with custom package name
hs sdk create typescript settlement-game --package-name @myorg/game-sdk

hs sdk create rust <spec-name>

Generate a Rust SDK crate for the specified spec.

# Generate with default settings (outputs to ./generated/<spec-name>-stack/)
hs sdk create rust settlement-game

# Generate with custom output directory
hs sdk create rust settlement-game --output ./crates/game-sdk

# Generate with custom crate name
hs sdk create rust settlement-game --crate-name game-sdk

The generated crate includes:

• Cargo.toml with hyperstack-sdk dependency
• src/lib.rs with re-exports
• src/types.rs with all data structs
• src/entity.rs with Entity trait implementations

Usage after generation:

# Add to your Cargo.toml
[dependencies]
hyperstack-sdk = "0.2"
settlement-game-stack = { path = "./generated/settlement-game-stack" }

use hyperstack_sdk::HyperStack;
use settlement_game_stack::{SettlementGame, SettlementGameEntity};

let hs = HyperStack::connect("wss://example.com").await?;
let game = hs.get::<SettlementGameEntity>("game_id").await;

Configuration Management

hs config init

Initialize a new hyperstack.toml configuration file.

hs config validate

Validate your configuration file.

Configuration File Format

The hyperstack.toml file defines your project and available specs. The CLI auto-discovers AST files, so minimal configuration is needed:

[project]
name = "my-hyperstack-project"  # required

[sdk]
output_dir = "./generated"              # optional, defaults to "./generated"
typescript_package = "hyperstack-react" # optional, npm package for generated SDK
rust_crate_prefix = "hyperstack"        # optional, prefix for generated Rust crate names

[build]
watch_by_default = true                 # optional, stream build progress

# Specs are auto-discovered from .hyperstack/*.ast.json files
# Only define [[specs]] if you need custom naming or explicit configuration
[[specs]]
name = "my-spec"                        # optional, defaults to kebab-case of entity
ast = "MyEntity"                        # required: entity name or path to .ast.json
description = "Optional description"    # optional

Minimal Configuration

For most projects, you only need:

[project]
name = "my-project"

The CLI will auto-discover all .hyperstack/*.ast.json files and derive spec names from entity names (e.g., SettlementGame → settlement-game).

Build Process

When you create a build, the following happens:

1. AST Validation: The spec's AST is validated
2. Upload: AST is uploaded to S3
3. Queue: Build is queued in CodeBuild
4. Build: Docker image is built from the AST
5. Push: Image is pushed to ECR
6. Deploy: Container is deployed to Kubernetes
7. Complete: WebSocket URL becomes available

Build statuses: pending -> uploading -> queued -> building -> pushing -> deploying -> completed/failed

Environment Variables

• HYPERSTACK_API_URL: Override the API URL (default: http://localhost:3000)

How It Works

The CLI uses AST serialization to generate SDKs and deployments efficiently:

1. The #[stream_spec] macro automatically serializes the AST to .hyperstack/<entity_name>.ast.json when you compile your spec
2. CLI auto-discovers AST files - no manual configuration required for simple projects
3. Push to cloud: The AST is uploaded and versioned
4. Build: CodeBuild compiles the AST into a deployable container
5. Deploy: The container runs as a WebSocket-accessible atom

This means:

• Zero-config for single-spec projects (just run hyperstack up)
• No need to recompile the CLI when adding new specs
• No feature flags or hardcoded registries
• Works with any spec in your workspace
• Content-addressed versioning (same AST = same version)
• Fast, efficient builds using pre-compiled base images

Troubleshooting

Error: "Not authenticated"

Run hs auth login to authenticate.

Error: "Spec 'xxx' not found"

Make sure the AST file exists at .hyperstack/<entity>.ast.json. Run:

hs sdk list

This shows all auto-discovered and configured specs.

Error: "AST file not found"

Run cargo build in your spec crate to generate the AST file at .hyperstack/<entity>.ast.json.

Error: "Spec has no versions"

Push your spec first:

hs spec push <spec-name>

Build failed

Check the build logs:

hs build logs <build-id>

License

Apache-2.0