Hosanna Tools

Hosanna Tools (hst) is the project CLI for Hosanna applications. Run it through the application lockfile:

npx hst version
npx hst --help

The checked-in samples currently use @tantawowa/hosanna-tools ^3.10.2. Treat the output of npx hst version and npx hst <command> --help as authoritative for the application you are working in.

First Project Check

From an application repository:

nvm use
npm ci
npx hst env check
npx hst compiler:status
npx hst target:list

env check reports missing or incompatible prerequisites. Use env fix only after reviewing the proposed changes:

npx hst env fix

Use config show to inspect the effective hosanna.json model:

npx hst config show

Build or Run

run owns the complete development lifecycle for a selected destination: resolve configuration, build where required, start supporting services, install or deploy, launch, and stream logs.

# Current sample Web workflow
npx hst run web dev browser

# Select interactively from available destinations
npx hst run

# Reuse the last interactive destination
npx hst run --last

# Native simulators
npx hst run ios dev sim --device "iPhone 17 Pro"
npx hst run apple-tv dev sim --device "Apple TV 4K"
npx hst run android dev sim --device "Pixel_8"
npx hst run android-tv dev sim --device "Television_1080p"

# Physical Roku
npx hst run roku dev device --device "living room"

build resolves and builds the same target without launching, deploying, opening a browser, or streaming logs:

npx hst build web dev emulator
npx hst build roku prod device
npx hst build ios dev sim --device "iPhone 17 Pro"

Before running an unfamiliar profile, inspect its plan:

npx hst run roku dev device \
  --app criterion \
  --dry-run \
  --explain

Use --format json when another tool needs the plan.

Platform, Target, and Device

These terms are independent:

Term	Examples	Meaning
Platform	web, roku, ios, apple-tv, android, android-tv	Runtime expression and platform build path
Environment	dev, qa, prod	Build-config overlay
Target	browser, emulator, sim, device	Where the expression runs
Device selector	name, IP, serial, UDID, AVD, preset	Which concrete destination to use

Discover destinations instead of guessing names:

npx hst target:list
npx hst target:list ios
npx hst device:list

emulator is a browser-hosted platform expression. sim is an Apple simulator or Android emulator. A browser profile is useful for shared behavior and layout checks, but it is not physical-device certification.

Run Configuration

Projects can store defaults and app/flavour profiles in .hosanna-tools/run.json. A selected app is passed with --app or HOSANNA_RUN_APP; a local build-config profile is selected with --profile or HS_BUILD_PROFILE.

npx hst run roku dev device --app criterion
HS_BUILD_PROFILE=local-debug npx hst run web dev browser

CLI arguments win over application and project defaults. Use --dry-run --explain to see where each resolved value came from. Production rejects a developer profile unless --allow-profile-in-prod is explicit.

Use --reuse to reuse a matching session and --replace to replace a conflicting one. HST otherwise refuses ambiguous ownership rather than silently connecting to an unrelated app.

Native Development Modes

Initialize and validate app-owned native projects with:

npx hst native:init ios
npx hst native:prepare ios
npx hst native:doctor ios

The same commands accept apple-tv, android, or android-tv.

Apple and Android targets default to bundled JavaScript for deterministic launches. Opt into the native development server with --hot-reload:

npx hst run apple-tv dev sim --device "Apple TV 4K" --hot-reload
npx hst run android-tv dev sim --device "Television_1080p" --hot-reload

Use --bundled for an explicit bundled run. --hot-reload and --bundled are mutually exclusive. Physical devices must be able to reach the development-server URL advertised by the host.

Build Config and AppConfig

Build config and AppConfig solve different problems:

• Build config resolves environment, platform, profile, secrets, and runtime infrastructure settings.
• AppConfig resolves presentation configuration and root-level $extendFile inheritance.

Inspect build config without exposing secret values:

npx hst build-config:resolve \
  --env dev \
  --platform web \
  --explain

Write the canonical runtime file:

npx hst build-config:resolve \
  --env prod \
  --platform roku \
  --out assets/meta/build-config.json

Resolve AppConfig:

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

The current public CLI resolves AppConfig JSON. It does not expose app-config:compile, app-config:clean, shape-delivery, font-delivery, or bundle-revision commands.

Generation and Compiler

Generate framework-owned source:

npx hst generate:all
npx hst generate:structs
npx hst generate:clean

Manage the project compiler:

npx hst compiler:status
npx hst compiler:list
npx hst compiler:install

With no explicit version, compiler:install uses transpiler-version from hosanna.json. Keep that version pinned so local development and CI use the same compiler.

SDK and Licensing

For licensed full-source projects:

npx hst license:activate "$HSC_LICENSE_KEY"
npx hst license:status
npx hst sdk:install
npx hst framework:update

license:activate stores a validated key in the user-level Hosanna key file. CI should inject the key from its secret manager and must not print or commit it.

framework:sync and framework:doctor are maintainer commands for managed framework forks; they are not normal application setup steps.

Roku

The normal development command is:

npx hst run roku dev device --device "<name-or-ip>"

Lower-level Roku commands are available when a pipeline needs them:

npx hst roku:run --help
npx hst roku:command keypress
npx hst roku:package --help
npx hst roku:map-stack --help

Use complib:package and complib:serve for app-owned Roku component-library output. Component-library build scripts live in the consuming/sample application, not in the framework repository.

Debugger and MCP

Start the debugger and the MCP server with:

npx hst debugger:start
npx hst mcp:start

hst run can start or reuse the services required by its selected workflow. Use the explicit commands when an editor or agent session needs the debugger independently.

See MCP Debugger Overview for connection and inspection workflows.

Regression Tests and RASP

Hosanna regression tests are Vitest tests using the Hosanna test fixture. Run the application repository's package scripts, for example:

npm run test:ui:web

There is no hst test:ui runner command. HST supplies launch, target, transport, diagnostic, screenshot, and reporting support to the Vitest integration.

Roku Automation Scripting Platform workflows use:

npx hst rasp:capture smoke
npx hst rasp:export <capture-id> smoke
npx hst rasp:validate rasp-scripts/smoke.rasp
npx hst rasp:run rasp-scripts/smoke.rasp

RASP capture is separate from the removed debugger test-recording command family.

Command Reference

See HST Command Reference for the current command inventory and high-value options.