Hinge CLI Reference

Hinge CLI Reference

Overview

Hinge is Janus’s built-in package manager. It enforces the Garden Wall doctrine: every published package is a signed, content-addressed Capsule with proof certificates, SBOM, and capability manifests. Trust is not assumed; it is proven.

All commands are available through janus pkg (which delegates to Hinge internally) or directly via the hinge binary.

---

Project Commands

janus init [name]

Scaffold a new Janus project with manifest, source directory, and git configuration.

janus init myproject

Creates the following structure:

myproject/
├── janus.kdl          # Project manifest
├── src/
│   └── main.jan       # Hello world starter
└── .gitignore

Arguments:

Argument	Required	Default	Description
name	No	myproject	Project directory and package name

Behavior:

• Creates the directory if it does not exist
• Generates a minimal janus.kdl manifest with name, version, and :core profile
• Writes a src/main.jan with a working hello-world program
• Initializes .gitignore with Janus build artifacts excluded

---

janus pkg resolve

Resolve dependencies declared in janus.kdl and generate a pinned lockfile.

janus pkg resolve

Behavior:

• Reads janus.kdl in the current directory
• Resolves version constraints against available packages in the registry
• Generates janus.lock with pinned versions and content IDs (CIDs)
• Incremental: only re-resolves changed or newly added dependencies
• Fails if any constraint is unsatisfiable (with diagnostics)

Output: janus.lock in the project root.

---

Package Commands

janus pkg pack <source> <name> <version>

Create a .jpk package archive from source.

janus pkg pack src mylib 1.0.0

Arguments:

Argument	Required	Description
source	Yes	Source directory to pack
name	Yes	Package name
version	Yes	Semantic version (MAJOR.MINOR.PATCH)

Output: {name}-{version}.jpk

What it does:

1. Normalizes file content (consistent line endings, sorted entries)
2. Computes a BLAKE3 content ID (CID) over the normalized archive
3. Generates an SBOM (Software Bill of Materials)
4. Bundles everything into a .jpk archive

---

janus pkg seal <package> --key <keyfile>

Sign a package archive with your Ed25519 identity key.

janus pkg seal mylib-1.0.0.jpk --key identity.key

Arguments:

Argument	Required	Description
package	Yes	Path to .jpk file
--key	Yes	Path to Ed25519 private key

What it does:

1. Computes Ed25519 signature over content hash + manifest + SBOM
2. Attaches the signature to the package
3. Package becomes tamper-evident — any modification invalidates the seal

---

janus pkg verify <package>

Verify a package’s integrity, authenticity, and trust status.

janus pkg verify mylib-1.0.0.jpk

Checks performed:

Check	Description
Content integrity	BLAKE3 CID matches actual archive contents
Signature validity	Ed25519 signature is mathematically correct
SBOM consistency	Declared dependencies match actual imports
Trust policy	Signer exists in your trust graph
Revocation status	Package has not been revoked by its author

Exit codes:

Code	Meaning
0	Verification passed
1	Verification failed (details printed to stderr)

---

janus pkg publish <package> --key <keyfile>

Publish a signed package to the federated registry.

janus pkg publish mylib-1.0.0.jpk --key identity.key

What it does:

1. Runs the full verification suite (same as janus pkg verify)
2. Announces the package via DMP gossip on topic $HINGE/{chapter}/{name}/announce
3. Appends an entry to the transparency ledger
4. Stores the archive in local Content-Addressed Storage (CAS)

Preconditions: The package must be sealed. Unsigned packages are rejected.

---

Identity Commands

janus pkg keygen <name>

Generate a new Ed25519 identity keypair for package signing.

janus pkg keygen myidentity

Output files:

File	Description
{name}.key	Ed25519 private key (keep secret)
{name}.pub	Ed25519 public key (share freely)

The corresponding DID is printed to stdout:

did:sovereign:z6Mkf5rGMoatrSj1f4CyvuHBeXJEhbSmYtwCDLmQ...

---

Trust Commands

janus pkg trust add <did>

Add a DID to your local trust graph.

janus pkg trust add did:sovereign:z6Mkf5r...

Packages signed by this identity will pass trust policy checks during verify and resolve.

---

janus pkg trust list

List all trusted DIDs and their trust distance.

janus pkg trust list

---

janus pkg trust remove <did>

Remove a DID from your trust graph.

janus pkg trust remove did:sovereign:z6Mkf5r...

Packages signed exclusively by this identity will no longer pass trust policy checks.

---

Inspection Commands

janus pkg status

Display project status: manifest summary, dependency count, and lock file health.

janus pkg status

---

janus pkg graph [--format dot|json|text]

Visualize the dependency graph.

janus pkg graph                    # Text tree (default)
janus pkg graph --format dot       # GraphViz DOT format
janus pkg graph --format json      # Machine-readable JSON

Formats:

Format	Use Case
text	Terminal inspection (default)
dot	Pipe to dot -Tpng for visual diagrams
json	CI integration and tooling

---

janus pkg audit

Run a security audit on all resolved dependencies.

janus pkg audit

Reports:

• Known vulnerabilities (from advisory database)
• License compatibility analysis
• Capability usage summary (which packages touch FS, Net, etc.)
• Unsigned or low-confidence packages flagged

---

janus pkg cache status

Show cache statistics: total size, entry count, and hit rate.

janus pkg cache status

---

janus pkg cache prune [--max-age <days>] [--max-size <MB>]

Clean up the local package cache.

janus pkg cache prune                       # Default eviction policy
janus pkg cache prune --max-age 30          # Remove entries older than 30 days
janus pkg cache prune --max-size 500        # Shrink cache to 500 MB

Options:

Option	Default	Description
--max-age	90	Maximum age in days before eviction
--max-size	2048	Maximum cache size in MB

---

Transparency Commands

janus pkg log show [--last <N>]

Show recent entries from the transparency ledger.

janus pkg log show              # All recent entries
janus pkg log show --last 10    # Last 10 entries

Each entry includes: timestamp, package CID, signer DID, and action (publish, revoke).

---

janus pkg log status

Show ledger health: entry count, last checkpoint hash, and integrity verification status.

janus pkg log status

---

Environment Variables

Variable	Default	Description
HINGE_CI	0	Set to 1 to enable CI mode (strict policy, offline, JSON output)
HINGE_OFFLINE	0	Set to 1 to prevent all network access
HINGE_CACHE_DIR	~/.hinge/cache	Package cache directory
HINGE_KEY	(none)	Default signing key path (avoids repeated --key flags)

---

CI Mode

When HINGE_CI=1 is set, Hinge operates under strict deterministic constraints:

Behavior	Description
Strict policy	No trust overrides or interactive prompts
Offline mode	Uses only cached and locked packages
Reproducible builds	Fails if lockfile is stale or missing
JSON output	All output is machine-parseable JSON
Mandatory proofs	SBOM and proof certificates required on publish
Non-interactive	All prompts auto-reject (no TTY assumed)

HINGE_CI=1 janus pkg resolve
HINGE_CI=1 janus pkg verify mylib-1.0.0.jpk

---

Manifest Format (janus.kdl)

The project manifest uses KDL syntax. This is the human-facing intent layer; Hinge resolves it into canonical JSON internally (per the Law of Representation).

project {
    name "mylib"
    version "1.0.0"
    profile "core"
    description "A sovereign math library"
    license "LUL-1.0"
    authors "did:sovereign:z6Mkf5r..."
}

dependencies {
    crypto "^2.1.0"
    logging "~1.0.0"
    math "=3.0.0"
}

Version Constraints

Prefix	Name	Meaning	Example
^	Compatible	Same major version	^1.2.3 matches >=1.2.3, <2.0.0
~	Approximate	Same minor version	~1.2.3 matches >=1.2.3, <1.3.0
=	Exact	Pin to specific version	=1.2.3 matches only 1.2.3
>=	Minimum	Floor constraint	>=1.0.0 matches any >=1.0.0

---

Content Addressing

All packages are identified by their BLAKE3 content ID (CID). The CID is computed over the normalized archive contents, ensuring that identical source always produces the same identifier regardless of build time or environment.

blake3:7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730

Format: blake3:<64-character-hex-digest>

This content-addressed design provides:

• Deduplication across the cache and registry
• Integrity verification without trusting the transport layer
• Reproducibility — same source always produces the same CID

---

Command Summary

Command	Description
janus init [name]	Scaffold a new project
janus pkg resolve	Resolve and lock dependencies
janus pkg pack <src> <name> <ver>	Create a .jpk archive
janus pkg seal <pkg> --key <key>	Sign a package
janus pkg verify <pkg>	Verify integrity and trust
janus pkg publish <pkg> --key <key>	Publish to registry
janus pkg keygen <name>	Generate Ed25519 keypair
janus pkg trust add <did>	Trust a signer
janus pkg trust list	List trusted identities
janus pkg trust remove <did>	Revoke trust
janus pkg status	Show project status
janus pkg graph [--format]	Visualize dependency graph
janus pkg audit	Security audit
janus pkg cache status	Cache statistics
janus pkg cache prune	Clean cache
janus pkg log show	Show ledger entries
janus pkg log status	Ledger health check