Hosanna Tools
Hosanna Tools is the project CLI shipped as @tantawowa/hosanna-tools. Use it through npx hst ... or an installed hst binary.
The current CLI groups are:
| Group | Purpose |
|---|---|
run:* | development execution: dev server, Roku run, debugger, MCP |
roku:* | Roku deployment and package signing |
generate:* | generated structs, command maps, and image helpers |
install:* | SDK, compiler, and template app setup |
ci:* | CI secret extraction and debug flag restoration |
secrets:* | portable .secrets management |
test:* | UI test recording and replay |
env:* | environment checks and cloud-agent setup |
Run:
npx hst --help
npx hst env
npx hst env --fix
hst env --fix can repair common SDK, compiler, and tools version mismatches.
Development
npx hst run:dev --vitePort 5170
run:dev runs Vite, generator watch, and optional debugger wiring. Useful options:
| Option | Default | Purpose |
|---|---|---|
--vitePort | 5173 | Vite dev server port |
--webAppPort | 59151 | web app debugger port |
--deviceAppPort | 59152 | device app debugger port |
--extensionPort | 59153 | extension debugger port |
--defaultClientType | web | extension target default |
--appName | unset | name shown for multi-app debugger sessions |
For only the debug proxy:
npx hst run:debugger
For MCP:
npx hst run:mcp
npx hst stop:mcp
Code Generation
npx hst generate
npx hst generate:structs src/path/MyView.ts
npx hst generate:clean
npx hst generate:9patch
generate creates Hosanna generated structs and command handler maps. Apps usually run it before TypeScript builds, tests, and platform builds.
Compiler Install
npx hst install:compiler
npx hst install:compiler 1.26.0
If no version is passed, tools read the project's hosanna.json compiler version and install ./bin/hsc. CI should set HSC_LICENSE_KEY and can set HSC_CACHE_DIR to reuse compiler downloads.
Roku Run and Package
Deploy a source folder or zip:
npx hst roku:run --source-root platforms/roku/src --log-output
npx hst roku:run --app-package ./build/app.zip
Package and sign:
npx hst roku:package --env prod
Important roku:package inputs:
| Flag | Environment fallback |
|---|---|
--ip | ROKU_IP |
--installer-password | ROKU_DEVPASSWORD |
--dev-id | ROKU_DEV_ID |
--signing-password | ROKU_DEV_PASSWORD |
--key-pkg | ROKU_PKG_NAME |
--key-pkg-base64 | ROKU_PKG_KEY_BASE64 |
Use --prebuild when packaging should run a build command first.
Secrets
Hosanna Tools can manage portable .secrets files:
npx hst secrets:init
npx hst secrets:list
npx hst secrets:check
npx hst secrets:exec -- npm run build
Do not commit .secrets. Commit .secrets.example with key names and empty/example values so secrets:check can verify local setup.
CI Helpers
Generate base64 debug flag secrets:
npx hst ci:extract-config
Restore them in CI:
npx hst ci:restore-flags
Extract a Roku signing key package for CI:
npx hst ci:extract-pkg-key myapp.pkg --base64-only
Use the resulting ROKU_PKG_KEY_BASE64 as a CI secret for roku:package.
UI Testing
Record and replay debugger-driven UI tests:
npx hst test:record
npx hst test:ui
npx hst test:ui recording-id --report-dir remote-debugging/reports
test:ui requires a running debug proxy and connected app. It can compare screenshots, update baselines, emit JSON, produce HTML/JUnit reports, and run coverage-only analysis.