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 application lockfile selects the HST version used by every command. Treat the output of npx hst version and npx hst <command> --help as authoritative for the application you are working in; do not substitute a globally installed CLI.

Hosanna Tools 3.18.0 introduced the canonical browser host name and the first-class Tizen/webOS build, setup, discovery, run, inspect, and terminate paths documented below. web remains a deprecated input alias for browser.

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.

# Shared Web DOM hosts
npx hst run browser dev emulator
npx hst run tizen dev emulator
npx hst run webos dev emulator

# 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"
npx hst run carplay dev sim --device "iPhone 17 Pro"
npx hst run android-auto dev sim --device "Hosanna_Phone_API_35"
npx hst run apple-watch dev sim --device "Apple Watch Series 11 (46mm)"
npx hst run wear-os dev sim --device "Hosanna_Wear_OS_API_36"

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

# Trusted physical TVs
npx hst run tizen dev device --device 192.168.1.20 \
  --signing-profile samsung-tv-dev
npx hst run webos dev device --device living-room

build runs the target's build-only plan without launching, deploying, opening a browser, or streaming logs. Packaged-TV plans bundle, stage, and package; Browser production assets remain owned by the host application's Vite build script.

npm run build:browser
npx hst build tizen prod device --signing-profile samsung-tv-dev
npx hst build webos prod device
npx hst build roku prod device
npx hst build ios dev sim --device "iPhone 17 Pro"

The Tizen and webOS build commands return an absolute .wgt or .ipk path and do not discover or contact a television. A device run adds vendor discovery, install, and launch.

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.

Installable Browser Builds

@tantawowa/hosanna-tools 3.16.0 adds the build-only hosannaPwaPlugin export from @tantawowa/hosanna-tools/vite. The host app supplies its manifest identity, artwork, start URL, offline page, and network-only routes. The plugin emits the generic install shell and uses a versioned, narrow caching policy for the current Vite bundle.

See Browser Progressive Web Apps (PWA) for the Vite 6 type boundary, complete configuration, runtime ownership, cache policy, and hosting checks.

Platform, Target, and Device

These terms are independent:

Term	Examples	Meaning
Platform	browser, tizen, webos, roku, ios, apple-tv, android, android-tv, carplay, android-auto, apple-watch, wear-os	HST runtime and build path; legacy web normalizes to browser
Environment	dev, qa, prod	Build-config overlay
Target	emulator, sim, device	Where the expression runs; legacy browser-like spellings normalize for compatibility
Device selector	name, IP, serial, UDID, AVD, preset	Which concrete destination to use

Discover destinations instead of guessing names:

npx hst device:setup tizen --host 192.168.1.20 \
  --signing-profile samsung-tv-dev --dry-run
npx hst device:setup webos --host 192.168.1.30 \
  --alias living-room --get-key
npx hst target:list
npx hst target:list ios
npx hst device:list
npx hst device:list --type tizen --json
npx hst device:list --type webos --json

emulator is a browser-hosted compile target. For Tizen and webOS it compiles the vendor initializer and keyboard bridge, but it is not a vendor simulator and cannot validate native TV services. sim is an Apple simulator or Android emulator.

device:setup automates only credential-safe vendor CLI steps and supports --dry-run. For Samsung it can connect with sdb, verify authorization, and verify an existing exact signing-profile name. Developer Mode, the TV prompt, certificate/DUID creation, and installation permission remain interactive. For LG it can register an ares alias and, with --get-key, hand control to the official interactive ares-novacom prompt before verifying device access. The Developer Mode account, Key Server switch, and passphrase entry remain interactive. HST never stores certificates, private keys, passwords, or passphrases.

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 browser dev emulator

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, android-tv, carplay, android-auto, apple-watch, or wear-os.

all covers all eight first-class native targets. Use cars for CarPlay + Android Auto or watches for Apple Watch + Wear OS when you only want one semantic surface group. watchos, wearos, and android-watch are accepted aliases; generated configuration uses canonical platform names.

Configure the consumer-owned Android Auto media service during initialization:

npx hst native:init android-auto \
  --android-auto-media-browser-service .media.PlaybackService

For an existing managed target, HST upgrades unchanged Android Auto config, manifest, discovery-descriptor, and Gradle templates. It preserves any edited file and warns which media declarations or dependency must be merged manually. Flattened Android component values are normalized to service class names in the generated manifest.

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.

Android Auto and Wear OS use bundled headless Hermes runtimes in this iteration. HST rejects --hot-reload for those targets before it starts native preparation or development services.

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.