Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

HelixSpec quick start (compile → run → verify)

Minimal, deterministic pipeline from human spec to replayable bundle.

1) Compile HelixSpec to canonical IR

helix compile examples/helixspec/demo.hxspec out/compile --deterministic

Writes ir.json, manifest.json, SHA256SUMS.txt, and a copy of the source spec. Use --deterministic to pin timestamps and hashes for reproducibility.

2) Run (compile → lower → execute)

helix helixspec-run examples/helixspec/demo.hxspec out/run \
  --deterministic \
  --policy-file policies/default.json

Produces:

  • ir.json (compiler output, canonical)
  • engine_edit_plan.json, engine_experiment_spec.json (IR→engine adapter)
  • results.json, receipts.json (engine execution + environment fingerprint)
  • manifest.json, SHA256SUMS.txt (all files hashed; sums exclude the sums file itself)

--policy accepts inline JSON; --policy-file reads a JSON policy from disk.

3) Verify a bundle

helix verify out/run --deterministic

Auto-detects HelixSpec bundles and re-hashes files against manifest.json and SHA256SUMS.txt. Deterministic mode pins verification timestamps.

4) Diff two bundles

helix diff out/run_A out/run_B

Accepts either bundle directories or individual manifest.json files.

Optional: enable Qt WebEngine smoke tests

Default CI and local headless runs skip WebEngine to avoid QtWebEngine crashes. To exercise the WebEngine suite:

HELIX_WEBENGINE_TESTS=1 xvfb-run -s "-screen 0 1920x1080x24" \
  tools/test.sh -q tests/test_web_panels_webengine_smoke.py

CI lane: trigger the webengine-smoke workflow (label run-webengine on a PR or workflow_dispatch). Environment defaults:

  • QT_QPA_PLATFORM=xcb
  • QTWEBENGINE_DISABLE_SANDBOX=1
  • QTWEBENGINE_CHROMIUM_FLAGS="--no-sandbox --disable-gpu"
  • HELIX_WEBENGINE_TESTS=1