CLI

helixor-pack inspects your license, compiles playbooks into packs, downloads catalog packs, and runs or serves a pack. helixor is a different program, the Helixor Code CLI (pipx install helixor); see Get started with the Helixor Code CLI. It owns the signup and license accept commands below.

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.

The CLI cannot mint or sign a license. Licenses are issued by Helixor; request one on the sign-up page. Changed in 0.3.1: the mint-license command is removed, and helixor-pack mint-license fails with invalid choice: 'mint-license'.

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. If it names a file that does not exist, the command exits 1 without trying the others.
3. ./helixor.hxlic in the working directory.
4. ~/.helixor/helixor.hxlic.

The Python loaders use the same order. The older name helixor.lic is still accepted in the two directories; a directory holding both names fails with LICENSE_LOCATION_AMBIGUOUS. If nothing is found, the command prints Error: LICENSE_NOT_FOUND: no Helixor license file was found., the six locations it checked and where to request a license, and exits 1. helixor-pack --help prints the search order. 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.

signup and license accept#

Available in the helixor package (the Helixor Code CLI) from 0.4.35; they are not helixor-pack commands. helixor signup creates your account and helixor license accept records your acceptance of a new agreement version before a license is issued or renewed. Both show the Helixor Software License Agreement and record which version you accepted.

helixor signup [--accept-license-agreement <sha256>]
helixor license accept [--accept-license-agreement <sha256>]

The licensing service checks the acceptance again and rejects a missing or mismatched one with HTTP 422 (LICENSE_AGREEMENT_NOT_ACCEPTED or LICENSE_AGREEMENT_MISMATCH). See Accept the license agreement.

Exit codes#

The messages behind code 1 are listed in Errors.

Environment#

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