CLI

helixor-pack inspects your license, compiles playbooks into packs, downloads catalog packs, and runs or serves a pack. helixor is the same program under a second name.

helixor-pack <command> [options]
helixor-pack --help
helixor-pack <command> --help

Both commands are installed with the runtime. See Installation.

Commands#

"Authority" is the Helixor licensing and compiler service at the URL in Environment.

License resolution#

Every command finds the license the same way. For inspect-license, the optional positional argument takes the place of --license.

1. --license <path>, if given. If that file does not exist, the command exits 1 without trying the others.
2. $HELIXOR_LICENSE_FILE.
3. ./helixor.lic in the working directory.
4. ~/.helixor/helixor.lic.

If nothing is found, it prints Error: No license file provided and default '…' not found. and exits 1. catalog and download-pack need a license too.

inspect-license#

helixor-pack inspect-license [LICENSE_FILE]

Verifies the signature and validity window, then prints a report. The report shows the license ID, organization, contact, tier and plan, status (ACTIVE (N days remaining) or IN GRACE PERIOD), expiry, grace period, licensed packs and solvers, and features. It does not print the content key. A tampered, not-yet-valid or expired file exits 1 with the reason. See License file.

compile#

helixor-pack compile --playbook PLAYBOOK --out OUT [--license LICENSE] [--remote] [--url URL]

A local compile validates the playbook, rejects declarations a compiled pack would not execute (UnsupportedPackDeclarationError, listing each problem), checks that your license allows the pack_id and any solvers, and encrypts with your license's content key. See Playbook schema for the checks and for what the pack will execute.

Compiling playbook 'internal_code_guard.yaml' locally...
Successfully compiled sealed binary pack (654 bytes): internal_code_guard.hxpack

catalog#

helixor-pack catalog [--license LICENSE] [--url URL]

Lists the pre-built packs on the authority. For each one it shows the pack ID, version, name, kind, description and invariants, and whether your license is entitled to it (✓ Entitled or ✗ Upgrade Required). Your license JSON is sent in a request header, so use only the HTTPS authority URL.

download-pack#

helixor-pack download-pack --pack-id PACK_ID [--license LICENSE] [--out OUT] [--url URL]

The authority seals the pack for your license. Re-download it after you renew; see Packs and manifest.

run#

helixor-pack run --pack PACK --text TEXT [--license LICENSE]

Unseals the pack in memory, evaluates TEXT once and prints the result as JSON. It makes no network calls.

helixor-pack run --pack internal_code_guard.hxpack --text "Release PROJ-ZEUS-9 today"

{
  "pack_id": "custom.internal_code_guard.v1",
  "action": "block_project_code",
  "invariants_passed": false,
  "reason": "Pack rule 'project_code' triggered (block)",
  "triggers": [
    {"rule_id": "project_code", "law": "compliance", "severity": "FATAL", "matched_items": ["PROJ-ZEUS-9"]}
  ],
  "remedy": {"clean_text": "[BLOCKED: Prohibited Content]", "redactions_count": 0, "redacted_categories": []},
  "…": "…",
  "license_status": "ACTIVE",
  "active_key_id": "ep1_2026",
  "active_epoch": 1,
  "edition": "DEVELOPER",
  "upgrade_notice": null
}

The output includes matched_items, so don't paste it into tickets or logs. edition, license_status, active_key_id and active_epoch come from the license the pack was unsealed with.

serve#

helixor-pack serve --pack PACK [--license LICENSE] [--host HOST] [--port PORT] [--token TOKEN]

Unseals the pack, prints Unsealed pack '<pack_id>' in RAM. Starting server on http://<host>:<port>, and serves the HTTP API in the foreground until stopped.

GET /v1/health reports the served pack_id and license tier; use it as the health check. The HTTP API page covers authentication, CORS and the remaining known issue.

Exit codes#

The messages behind code 1 are listed in Errors.

Environment#

The CLI also loads a .env file at start-up. See Configuration.