Helix CLI docs

Browse Helix CLI docs

Governance & Licensing (Public Contract)

This page is the public contract for how Helix treats authority, signatures, and verification. It exists to prevent “sales/support drift” and to keep trust properties stable over time.

Definitions

Exploratory: you can simulate and explore locally, but outputs are not “decision-grade”.
Decision-grade: Helix is asserting governance-level guarantees under an explicit license and policy.
Studio Team license: licensed Omnis Helix + CLI authoring for local decision-grade work without a shared control plane.
Governance Workspace: the shared Teams/Hub/Registry layer for approvals, RBAC, proof links, audit export, and durable decision state.
Private deployment: a customer-managed Governance Workspace running in the customer's VPC, private cloud, or on-prem environment.
Signed bundle: an artifact bundle that includes license lineage plus an attestation signature.
Verification: offline checks that a bundle’s hashes, license lineage, and signatures are valid.

The rules (non-negotiable)

Exploratory runs are always allowed.
Decision-grade requires a Governance license.
Signed bundles include license lineage plus an attestation.
Verification is always free and offline.
Verification fails closed for decision-grade claims.
- Unsigned bundles cannot verify as decision-grade.
- Bundles with invalid manifests/attestations cannot verify.

What is (and isn’t) paywalled

Free users may compute: simulate, explore, export exploratory artifacts.
Licensed Studio users may assert: decision-grade outputs and signed bundles on local desktop/CLI workflows.
Governance Workspace customers may add: shared approvals, proof links, audit export, and durable review state.
Private deployment customers may run that Governance Workspace inside their own environment.

Commercial surfaces

Desktop proof: downloadable Studio + CLI + offline verifier for exploratory evaluation.
Studio Team: commercial local authoring with decision-grade signing.
Governance Workspace: shared Helix-operated or customer-operated Teams/Hub/Registry for program-level review workflows.
Private deployment: customer-managed Governance Workspace with customer identity, storage, keys, and runner fleet.

Optional seat entitlements

Licenses may include optional commercial entitlements under entitlements, currently:

entitlements.seats.min: optional minimum seats for the agreement (informational)
entitlements.seats.max: optional maximum allowed seats (enforceable)

Helix is sold primarily by licensed authoring scope, workspace coverage, and deployment posture, not by raw seat count. Seat entitlements remain optional secondary controls.

Helix treats seat enforcement as offline-first:

Local usage uses a stable seat_id (derived from user + host + license) unless overridden via HELIX_SEAT_ID.
Teams usage is measured via active API tokens (admin-only telemetry endpoint).

CLI helpers:

# Offline license parse + validity snapshot
helix license status --license /path/to/license.json --edit-program-id <edit_program_id> --json

# Seat usage: local + Teams (token is required for server queries)
helix license seats \
  --license /path/to/license.json \
  --edit-program-id <edit_program_id> \
  --teams-server https://teams.example.com \
  --teams-token "$HELIX_REGISTRY_TOKEN" \
  --enforce \
  --json

# Teams-side seat telemetry (admin only)
helix teams seats --server "$HELIX_REGISTRY_URL" --token "$HELIX_REGISTRY_TOKEN" --json

Migration (distribution rename)

If you previously installed the legacy PyPI distribution veri-helix, migrate with:

python -m pip uninstall -y veri-helix
python -m pip install -U helix-governance

This is a packaging rename only:

Module namespace stays helix
CLI entrypoint stays helix
Omnis Helix entrypoint is omnis-helix

Bundle signing + verification (CLI)

Configure license (offline)

HELIX_LICENSE_PATH=/path/to/license.json
HELIX_EDIT_PROGRAM_ID=<edit_program_id>

Build a signed bundle

helix artifacts build \
  --config cfg.json \
  --outdir out/bundle \
  --sign \
  --signing-key /path/to/signer.ed25519

The signed bundle includes:

governance/license.json (license lineage)
governance/attestation.json (signature over the bundle identity)

Verify (always free + offline)

helix verify out/bundle
helix verify out/bundle.zip

Verification never reads your local license file; it only validates what is inside the bundle.

Trust chain (diagram)

Helix (issuer)  ──signs──▶  License (helix-license.v1)         [pinned issuer keys in the build]
                                 │
                                 ▼
Decision-grade run summary includes provenance.license:
  license_id, license_sha256, issuer_key_id, org, edit_program_id
                                 │
                                 ▼
Signed bundle:
  manifest.json (hashes) + governance/attestation.json (signature over bundle identity)
                                 │
                                 ▼
Verifier (free, offline):
  checks manifest hashes + license signature + attestation signature  →  VERIFIED / FAILED

Provenance header format (exports + reports)

Every human-facing export surface includes:

A single-line provenance header (stable formatting).
A small JSON block with the same fields (machine readable).

Surfaces:

*.export.json (provenance_header, provenance_block)
*.evidence.json (provenance_header, provenance_block)
HTML report (rendered as a “Provenance” panel)

Header line is always in a fixed field order (placeholders do not reorder fields):

Helix provenance: mode=<MODE> policy=<POLICY> license=<LICENSE> issuer=<ISSUER> attestation=<ATTESTATION>

Policy label selection:

Prefer policy_id when present.
Else fall back to policy_profile when present.
Else fall back to short policy_hash (sha256:<first10>).

Missing values render as none (or unknown for policy when no policy fields exist).

CLI session contract (v3)

The user-facing Helix CLI session lifecycle is treated as a versioned external contract (bytes on disk), not an internal implementation detail.

See: Helix CLI Session Contract v3.

CI usage patterns (copy/paste)

Typical decision-grade CI flow:

python -m pip install -U helix-governance

export HELIX_LICENSE_PATH=/path/to/license.json
export HELIX_EDIT_PROGRAM_ID=<edit_program_id>
export HELIX_POLICY_PATH=/path/to/policy.json   # optional

# Optional: audit pinned issuer key ids (offline).
helix license issuer-keys --json > helix_issuer_keys.json

# Offline readiness snapshot (no secrets).
helix governance self-check \
  --json \
  --strict \
  --decision-mode decision_grade \
  --signing-key /path/to/signer.ed25519 \
  > helix_governance_self_check.json

# Build a signed bundle (license-gated) and verify it (always free + offline).
helix artifacts build \
  --config cfg.json \
  --outdir out/bundle \
  --sign \
  --signing-key /path/to/signer.ed25519

helix verify out/bundle --json-out helix_verify_bundle.json

If you need a single artifact for support tickets / CI logs, also capture:

helix support bundle --out helix_support_bundle.zip

Studio launch (optional)

Omnis Helix uses the same env vars:

export HELIX_LICENSE_PATH=/path/to/license.json
export HELIX_EDIT_PROGRAM_ID=<edit_program_id>

omnis-helix

If you do not need shared approvals, proof links, or audit export, you can stay on the local Studio/CLI surface. Private deployment only applies when the shared Governance Workspace must run inside your own environment.

Canonical error codes

All governance hard-stops surface one of these codes:

LICENSE_REQUIRED
LICENSE_INVALID
LICENSE_EXPIRED
LICENSE_NOT_YET_VALID
LICENSE_SCOPE_MISMATCH
SIGNING_KEY_REQUIRED
POLICY_LOCK_VIOLATION
ATTESTATION_INVALID
MANIFEST_MISMATCH