Use the tools

CLI reference

Every maelys-policy command, argument, output, exit status and common workflow.

maelys-policy is an offline policy compiler and inspection tool. It reads files, writes a canonical policy artifact when asked, and never launches a workload or contacts the network.

Command map

Command	Input	Output	Purpose
`compile SOURCE.json -o POLICY.mir`	JSON manifest	binary MIR file	create a portable decision
`validate POLICY.mir`	binary MIR	confirmation on stdout	reject malformed or non-canonical policy
`inspect POLICY.mir`	binary MIR	readable JSON on stdout	review the normalized meaning
`hash POLICY.mir`	binary MIR	`sha256:…` on stdout	identify the decision
`artifact-hash FILE`	any file	`sha256:…` on stdout	identify source/package bytes
`--version`	none	product version on stdout	report the installed release

There are no global configuration files and no environment variables that change policy semantics.

`compile`

CODE

maelys-policy compile SOURCE.json -o POLICY.mir

Example:

CODE

maelys-policy compile policies/audit.json -o build/audit.mir

The command:

reads at most 1 MiB from SOURCE.json;
parses strict JSON source v2;
validates and normalizes every decision;
encodes canonical MIR v2;
writes exactly the path following -o.

Success is silent. An invalid argument order prints usage and exits with status 2. A parse, validation, I/O or allocation failure prints maelys-policy: <result>: <diagnostic> to standard error and exits with status 1.

-o is mandatory and must appear between the source and output exactly as shown. The CLI currently does not read policy source from stdin and does not overwrite stdout with binary bytes.

`validate`

CODE

maelys-policy validate POLICY.mir

Example output:

CODE

valid MIR v2

Validation checks the magic, version, limits, enum values, reserved bytes, record ordering, duplicates, UTF-8/path constraints, destination constraints and absence of trailing data. The decoder reconstructs the decision and requires re-encoding to produce byte-for-byte identical output.

`inspect`

CODE

maelys-policy inspect POLICY.mir

It writes deterministic, formatted JSON to stdout, so it composes naturally:

CODE

maelys-policy inspect policy.mir
maelys-policy inspect policy.mir > review.json
maelys-policy inspect policy.mir | jq '.network'

The inspection document exposes the normalized decision but is non-normative. Do not sign or hash it as a substitute for the MIR file.

`hash`

CODE

maelys-policy hash POLICY.mir

Output:

CODE

sha256:2c6f…64-lowercase-hex-digits…

The digest covers the complete canonical MIR byte sequence. Equivalent manifests compile to the same decision and therefore the same digest. Warden can carry this value into an execution receipt.

`artifact-hash`

CODE

maelys-policy artifact-hash FILE

This hashes arbitrary bytes exactly as stored. Use it for provenance of a JSON source, package or build artifact:

CODE

maelys-policy artifact-hash policies/audit.json

It deliberately has a different command name because an artifact fingerprint is not a policy decision identity. Whitespace changes the source artifact hash but may leave the compiled MIR hash unchanged.

`--version`

CODE

maelys-policy --version

The output is the Sandbox Policy product release, for example 0.3.0. It is independent of the MIR binary format version and the public C ABI version.

Exit status contract

Status	Meaning
`0`	operation completed successfully
`1`	input, validation, memory or I/O operation failed
`2`	invocation shape or command name is invalid

Diagnostics go to stderr. Machine-readable results (inspect, hash, artifact-hash) go to stdout.

Common workflows

Review a policy in CI:

CODE

set -eu
maelys-policy compile policy.json -o policy.mir
maelys-policy validate policy.mir
maelys-policy inspect policy.mir > policy.review.json
maelys-policy hash policy.mir > policy.digest

Prove two source files resolve to the same decision:

CODE

maelys-policy compile first.json -o first.mir
maelys-policy compile second.json -o second.mir
test "$(maelys-policy hash first.mir)" = "$(maelys-policy hash second.mir)"

Run the result with Warden:

CODE

maelys-warden run --plan policy.mir --receipt run.json -- npm test -- --runInBand

Everything after Warden's -- is the workload command and its arguments. Those arguments are not parsed by maelys-policy.