HST Command Reference

Run HST through the application lockfile:

npx hst version
npx hst --help
npx hst <command> --help

This page reflects the 3.10.2-next command surface used during this documentation update. The installed command help remains authoritative.

Global Options

Option	Purpose
--help	Print command-specific help
--version	Print version information
--verbose	Enable verbose HST logging

Environment and Project Configuration

Command	Purpose
version	Print the HST version
env check	Inspect Node, project, compiler, platform, and tool prerequisites
env fix	Apply supported environment repairs
env prepare-gitignore	Add supported generated/secret paths to .gitignore
config show	Print current hosanna.json configuration
config set	Update a curated configuration value
config wizard	Configure the project interactively
secrets:init	Create .secrets from .secrets.example when absent
secrets:list	List secret keys without values
secrets:check	Compare .secrets with its template
secrets:exec	Run a command with .secrets loaded into its environment

Examples:

npx hst env check
npx hst config show
npx hst secrets:check
npx hst secrets:exec -- npm run build

Target Discovery

Command	Purpose
target:list [platform]	Discover browser presets, simulators, emulators, and devices
device:list	Merge discovered devices with .hosanna-tools/devices.json preferences

npx hst target:list
npx hst target:list apple-tv
npx hst device:list

Run

hst run [platform] [env] [target] [deviceSelector]

Supported platforms are web, roku, ios, apple-tv, android, and android-tv.

Important options:

Option	Purpose
--device <selector>	Select an IP, serial, UDID, AVD, simulator, device name, or browser preset
--app <key>	Select an app/flavour from run configuration
--profile <name>	Add a build-config developer profile
--app-config <selector>	Select runtime AppConfig
--hot-reload	Use a supported native JS development server
--bundled	Use bundled native JavaScript/assets
--reuse	Reuse a matching HST session
--replace	Replace a conflicting session or occupied device resource
--last	Reuse the last interactive destination
--no-open	Do not open the browser
--no-build	Skip the platform build for device runs
--no-logs	Do not stream device logs
--dry-run	Print the resolved run plan without executing it
--explain	Include configuration-source details in text plan output
--format text|json	Select plan/result format
--non-interactive	Fail instead of prompting
--hsconfig <path>	Select an explicit native/Roku hsconfig
--hsc-project <path>	Select an explicit Roku compiler project

Port overrides are --vitePort, --managementPort, --webAppPort, --deviceAppPort, and --extensionPort.

Examples:

npx hst run web dev browser
npx hst run ios dev sim --device "iPhone 17 Pro"
npx hst run android-tv dev sim --device "Television_1080p" --hot-reload
npx hst run roku dev device --device "living room"
npx hst run roku prod device --app criterion --dry-run --explain

Build

hst build [platform] [env] [target] [deviceSelector]

build shares platform, environment, target, device, app, profile, AppConfig, native-mode, config-selection, dry-run, and output-format options with run. It does not launch, deploy, open a browser, or stream logs.

npx hst build web dev emulator
npx hst build roku prod device --hsc-project platforms/hsconfig-roku.prod.json
npx hst build ios dev sim --device "iPhone 17 Pro"

Build Config

Command	Purpose
build-config:resolve	Resolve tracked, secret, platform, environment, and profile overlays
build-config:restore-secrets	Restore ignored overlays from BUILD_CONFIG_SECRETS_*_BASE64 variables

build-config:resolve options:

Option	Purpose
--env <name>	Environment; falls back to HS_ENV or HOSANNA_BUILD_ENV
--platform <name>	Platform; falls back to HS_PLATFORM or HOSANNA_BUILD_PLATFORM
--profile <name>	Optional developer profile; falls back to HS_BUILD_PROFILE
--allow-profile-in-prod	Explicitly permit a developer profile in production
--out <path>	Write resolved JSON
--manifest-out <path>	Write a sanitized source manifest
--format json	Print JSON to stdout
--explain	Print sources without secret values

AppConfig

Command	Purpose
app-config:resolve	Resolve an AppConfig file and root-level $extendFile inheritance

Options are --input, --cwd, --expression, --platform, and --out.

npx hst app-config:resolve --expression tv --platform roku
npx hst app-config:resolve --input app.config.phone.json --out /tmp/app-config.json

The current CLI does not provide app-config:compile or app-config:clean.

Native Projects

Command	Purpose
native:init [platform]	Initialize app-owned native thin projects and configuration
native:prepare [platform]	Run lightweight native prebuild validation
native:doctor [platform]	Diagnose native prerequisites and print fixes

Supported native platform selectors are ios, apple-tv, android, and android-tv.

Code and Asset Generation

Command	Purpose
generate:all	Generate structs and command-handler maps
generate:structs [files...]	Generate structs for selected files or the project
generate:clean	Remove generated output managed by HST
generate:9patch	Generate 9-patch assets
game:prep-level <input>	Normalize Tiled JSON to the canonical Hs2d runtime subset

Compiler, SDK, and Framework

Command	Purpose
compiler:install [version]	Install bin/hsc; default version comes from hosanna.json
compiler:status	Report configured and installed compiler state
compiler:list	List versions known from configuration, Keygen, installation, and cache
sdk:install	Install the configured SDK distribution
framework:update	Update a Keygen-distributed framework checkout to its pinned version
framework:sync	Maintainer workflow for managed client forks
framework:doctor	Validate managed client forks and pins
template:create	Create a template application with the SDK

Licensing

Command	Purpose
license:activate <key>	Validate and store a framework license key
license:status	Validate the stored key and print entitlements

Do not pass real keys in logs or committed scripts. Prefer environment or secret-manager injection.

Roku

Command	Purpose
roku:run	Deploy an app zip or folder
roku:command <command>	Send an app command through ECP
roku:package	Package and sign a channel with roku-deploy
roku:map-stack	Map BrightScript stack/compile locations through .brs.map files
ci:extract-pkg-key <pkg>	Extract a Roku signing key as base64 for CI storage
complib:package	Package built standalone component-library output
complib:serve	Serve component-library archives for an on-device development loop

Use hst run roku ... for normal development. Use the lower-level commands for explicit pipeline steps.

Debugger and MCP

Command	Purpose
debugger:start	Start the command-debugger WebSocket proxy
mcp:start	Start the Hosanna MCP server
mcp:stop	Stop the server represented by the MCP lock/PID file
dev:start	Run configured local Vite, generator-watch, and optional debugger processes

Capture and RASP

Command	Purpose
capture [platform]	Record an Apple simulator, capture-card input, or macOS screen/window
rasp:capture <name>	Record input and export a RASP script
rasp:export <captureId> <name>	Export a saved input capture as RASP YAML
rasp:validate <file>	Validate RASP grammar without a device
rasp:run <file>	Execute a RASP script against a connected app

Hosanna UI regression tests run through application-owned Vitest scripts. There is no hst test:ui command and no generic debugger test command.