hs build

Advanced low-level build management commands. Most users should use hs up instead, which handles builds automatically.

The build commands are hidden from the default help output and are intended for advanced users and debugging.

When to Use Build Commands

Debugging build failures - Get detailed build status and logs
CI/CD pipelines - Separate push, build, and deploy stages
Testing builds - Create builds without deploying
Build monitoring - Track build progress programmatically

Subcommands

hs build create - Create a new build
hs build list - List builds
hs build status - Get detailed build status

create

Create a new build from a stack. Watches progress by default.

Usage

hs build create STACK_NAME [OPTIONS]

Arguments

stack_name

string

required

Name of the stack to build

Options

--version

integer

Use specific stack versionDefault: latest version

--ast-file

string

Use local stack file directly instead of a pushed versionBypasses version management - useful for testing local changes without pushing.

--no-wait

boolean

Don’t wait for build to complete (return immediately)Returns the build ID immediately without watching progress.

Examples

Build Latest Version

hs build create nft-indexer

Output:

Creating build for 'nft-indexer' (version 3)...

Build ID: 12

[1/4] Parsing stack definition... ✓
[2/4] Compiling transformations... ✓
[3/4] Building container image... 67%

Build Specific Version

hs build create nft-indexer --version 2

Build from Local File

hs build create nft-indexer --ast-file ./stacks/nft-indexer.stack

Useful for testing changes without pushing:

# Test local changes
hs build create my-stack --ast-file ./stacks/my-stack.stack --no-wait

# If successful, push and deploy
hs up my-stack

Create Build Without Waiting

hs build create nft-indexer --no-wait

Output:

Creating build for 'nft-indexer' (version 3)...

Build ID: 12
Status: pending

Build started. Use 'hs build status 12' to check progress.

Build Stages

Parsing - Validate stack definition syntax
Compilation - Compile transformations and generate code
Container Build - Build Docker image with runtime
Registry Push - Push image to container registry

Return Value

Returns the build ID, which can be used with other commands:

# Create build
BUILD_ID=$(hs build create my-stack --no-wait --json | jq -r '.build_id')

# Watch progress
hs build status $BUILD_ID --watch

list

List recent builds with their status.

Usage

hs build list [OPTIONS]

Options

--limit

integer

default:"20"

Maximum number of builds to show

--status

string

Filter by statusValid values: pending, building, completed, failed, cancelled

--json

boolean

Output in JSON format

Examples

List Recent Builds

hs build list

Output:

ID    STACK           VERSION   STATUS      CREATED              DURATION
  nft-indexer     v3        completed   2026-03-02 10:30     2m 34s
  token-tracker   v5        completed   2026-03-02 09:15     1m 52s
  nft-indexer     v3        failed      2026-03-02 08:00     45s
  nft-indexer     v2        completed   2026-03-01 16:20     2m 10s

Filter by Status

hs build list --status failed

Output:

ID    STACK           VERSION   STATUS   CREATED              ERROR
13    nft-indexer     v3        failed   2026-03-02 08:00     Syntax error at line 23
10    token-tracker   v4        failed   2026-03-01 12:00     Out of memory

Limit Results

hs build list --limit 5

JSON Output

hs build list --json

[
  {
    "id": 15,
    "stack_name": "nft-indexer",
    "version": 3,
    "status": "completed",
    "created_at": "2026-03-02T10:30:00Z",
    "completed_at": "2026-03-02T10:32:34Z",
    "duration_seconds": 154
  }
]

status

Get detailed status for a specific build.

Usage

hs build status BUILD_ID [OPTIONS]

Arguments

build_id

integer

required

Build ID to check

Options

--watch

boolean

Watch build progress until completionUpdates in real-time until the build completes or fails.

--json

boolean

Output in JSON format

Examples

Check Build Status

hs build status 15

Output:

Build ID: 15
Stack: nft-indexer (version 3)
Status: completed
Created: 2026-03-02 10:30:00 UTC
Completed: 2026-03-02 10:32:34 UTC
Duration: 2m 34s

Stages:
  [1/4] Parsing stack definition... ✓ (2s)
  [2/4] Compiling transformations... ✓ (45s)
  [3/4] Building container image... ✓ (1m 30s)
  [4/4] Pushing to registry... ✓ (17s)

Container Image:
  registry.usehyperstack.com/nft-indexer:build-15
  Size: 245 MB

Watch Build Progress

hs build status 15 --watch

Output (updates in real-time):

Build ID: 15
Stack: nft-indexer (version 3)
Status: building

[1/4] Parsing stack definition... ✓
[2/4] Compiling transformations... ✓
[3/4] Building container image... 67%
[4/4] Pushing to registry...

Failed Build

hs build status 13

Output:

Build ID: 13
Stack: nft-indexer (version 3)
Status: failed
Created: 2026-03-02 08:00:00 UTC
Failed: 2026-03-02 08:00:45 UTC
Duration: 45s

Error: Syntax error in stack definition
Line 23: Unexpected token '}'

Stages:
  [1/4] Parsing stack definition... ✗
  [2/4] Compiling transformations... (skipped)
  [3/4] Building container image... (skipped)
  [4/4] Pushing to registry... (skipped)

Logs:
  stacks/nft-indexer.stack:23:5
     21 |   }
     22 | 
  >  23 |   }
        |     ^
     24 | }
  
  Error: Unexpected closing brace

JSON Output

hs build status 15 --json

{
  "id": 15,
  "stack_name": "nft-indexer",
  "version": 3,
  "status": "completed",
  "created_at": "2026-03-02T10:30:00Z",
  "completed_at": "2026-03-02T10:32:34Z",
  "duration_seconds": 154,
  "stages": [
    {
      "name": "parse",
      "status": "completed",
      "duration_seconds": 2
    },
    {
      "name": "compile",
      "status": "completed",
      "duration_seconds": 45
    },
    {
      "name": "build",
      "status": "completed",
      "duration_seconds": 90
    },
    {
      "name": "push",
      "status": "completed",
      "duration_seconds": 17
    }
  ],
  "image": "registry.usehyperstack.com/nft-indexer:build-15",
  "image_size_mb": 245
}

Build Status Values

pending - Build queued, not started yet
building - Build in progress
completed - Build successful
failed - Build failed (see error message)
cancelled - Build cancelled by user or system

CI/CD Example

Separate stages for testing:

#!/bin/bash
set -e

# 1. Push stack
echo "Pushing stack..."
hs stack push my-stack

# 2. Create build
echo "Creating build..."
BUILD_ID=$(hs build create my-stack --no-wait --json | jq -r '.build_id')
echo "Build ID: $BUILD_ID"

# 3. Wait for build
echo "Waiting for build to complete..."
hs build status $BUILD_ID --watch

# 4. Check build status
STATUS=$(hs build status $BUILD_ID --json | jq -r '.status')
if [ "$STATUS" != "completed" ]; then
  echo "Build failed!"
  hs build status $BUILD_ID
  exit 1
fi

echo "Build successful!"

# 5. Deploy (manual or automatic)
# hs deploy $BUILD_ID --branch production

Error Handling

Stack Not Found

Error: Stack 'my-stack' not found

Solution: Check the stack name or push it first:

hs stack push my-stack

Build Not Found

Error: Build #999 not found

Solution: Verify the build ID with hs build list.

Build Failed

Error: Build #13 failed

Solution: Check the error details:

hs build status 13

Return Codes

0 - Success
1 - Error (build failed, not found, etc.)

hs up - High-level deploy (recommended)
hs stack push - Push stacks
hs stack rollback - Rollback to previous build

CLI Tools

Commands

Documentation Index

​hs build

​When to Use Build Commands

​Subcommands

​create

​Usage

​Arguments

​Options

​Examples

​Build Latest Version

​Build Specific Version

​Build from Local File

​Create Build Without Waiting

​Build Stages

​Return Value

​list

​Usage

​Options

​Examples

​List Recent Builds

​Filter by Status

​Limit Results

​JSON Output

​status

​Usage

​Arguments

​Options

​Examples

​Check Build Status

​Watch Build Progress

​Failed Build

​JSON Output

​Build Status Values

​CI/CD Example

​Error Handling

​Stack Not Found

​Build Not Found

​Build Failed

​Return Codes

​Related Commands

Build docs developers (and LLMs) love

hs build

When to Use Build Commands

Subcommands

create

Usage

Arguments

Options

Examples

Build Latest Version

Build Specific Version

Build from Local File

Create Build Without Waiting

Build Stages

Return Value

list

Usage

Options

Examples

List Recent Builds

Filter by Status

Limit Results

JSON Output

status

Usage

Arguments

Options

Examples

Check Build Status

Watch Build Progress

Failed Build

JSON Output

Build Status Values

CI/CD Example

Error Handling

Stack Not Found

Build Not Found

Build Failed

Return Codes

Related Commands