CLI Reference

This page describes how to use the policy-engine binary once it is installed and available on your PATH.

The CLI works with three file categories:

• template source files, typically *.template
• compiled bytecode files, typically *.bin
• JSON intent and evidence objects

Examples on this page use paths such as examples/..., relative to this guide set. Adjust those paths to match where your template and JSON files live.

Top-level command

policy-engine <COMMAND>

Commands:

• compile
• print
• eval

compile

Compile template source into bytecode.

Usage:

policy-engine compile [OPTIONS] <TEMPLATE>

Arguments:

• <TEMPLATE>: path to the template source file

Options:

• --out <OUT>: output path for the compiled bytecode; defaults to out.bin

Behavior:

• reads the template source file
• parses and validates the template
• compiles it into bytecode
• writes the bytecode to the output path
• prints a policy_template_id=... line to standard output

Example:

policy-engine compile examples/clothing_purchase.template \
  --out clothing_purchase.bin

Example output:

policy_template_id=4Bh9qrxKWLfPEUFs6hKqtzL75dPQyj9hSLHmDr8wqDap

Exit codes:

• 0: success
• 1: failure

Notes:

• Bytecode generation is deterministic, so the same template always produces the same template ID.
• If the template contents change in a way that changes the compiled policy, the template ID changes too.
• Whitespace, comments, schema field order, and set literal element order do not define the policy. The compiled fields, constraints, literal values, and template name do.

print

Load bytecode and show a readable rendering of the compiled template.

Usage:

policy-engine print <BYTECODE>

Arguments:

• <BYTECODE>: path to a compiled bytecode file

Behavior:

• reads the bytecode file
• decodes it into a compiled policy template
• prints a readable representation to standard output

Example:

policy-engine print clothing_purchase.bin

Example output:

name clothing_purchase_guard

intent {
  acceptable_brands: optional set<string>
  acceptable_categories: set<string>
  acceptable_colors: optional set<string>
  audience: string
  max_price_cents: int
  size: string
}

evidence {
  audience: string
  brand: string
  category: string
  color: string
  price_cents: int
  size: string
}

requires {
  evidence.category in intent.acceptable_categories;
  evidence.size == intent.size;
  evidence.audience in {"men", "unisex", "women"};
  evidence.audience == intent.audience;
  evidence.price_cents <= intent.max_price_cents;
  optional: evidence.color in intent.acceptable_colors;
  optional: evidence.brand in intent.acceptable_brands;
}

Exit codes:

• 0: success
• 1: failure

Notes:

• print is for inspection of the compiled template.
• It does not preserve comments or original source formatting.
• Exact whitespace and layout should be treated as readable output, not a formatting contract.

eval

Evaluate compiled bytecode against JSON intent and evidence.

Usage:

policy-engine eval [OPTIONS] --evidence <EVIDENCE> <BYTECODE>

Arguments:

• <BYTECODE>: path to a compiled bytecode file

Options:

• --evidence <EVIDENCE>: path to the evidence JSON object
• --intent <INTENT>: path to the intent JSON object; if omitted, the CLI behaves as though intent were {}
• --check-id <ID>: expected template ID to compare against the compiled bytecode before evaluation

Behavior:

• reads and decodes the bytecode
• optionally checks the expected template ID
• reads intent and evidence JSON files
• validates the JSON objects against the template schemas
• evaluates all constraints in source order

JSON input encoding

The template defines typed intent and evidence schemas. The CLI reads values for those schemas from JSON files.

Template type	JSON form
bool	JSON boolean
int	JSON integer in signed 64-bit range
string	JSON string
date	JSON string in YYYY-MM-DD format
set<int>	JSON array of integers
set<string>	JSON array of strings
set<date>	JSON array of YYYY-MM-DD strings

Input rules:

• the top-level JSON value must be an object
• required schema fields must be present
• extra fields are rejected
• optional intent fields may be omitted
• if an optional field is present, it must still have the declared type
• duplicate values in JSON arrays for sets are ignored when loaded
• date strings must use YYYY-MM-DD and must be valid calendar dates

Example:

policy-engine eval clothing_purchase.bin \
  --intent examples/clothing_purchase.intent.json \
  --evidence examples/clothing_purchase.evidence.json

Successful output:

decision=pass

Validation failure output:

decision=fail
input validation error: ...

Constraint failure output:

decision=fail
constraint[<index>] failed: ... (...)
constraint[<index>] error: ... (...)

Exit codes:

• 0: the policy passed
• 1: the policy failed, input validation failed, or an operational error occurred

Notes:

• The index in constraint[<index>] starts at 0.
• If --intent is omitted and the template declares required intent fields, input validation fails because {} does not contain those fields.
• Input validation errors are reported instead of constraint result lines.
• Operational errors, such as unreadable files or invalid bytecode, are reported without a decision= line.
• --check-id is useful when you want to verify that a bytecode file matches a specific template ID before evaluating it.

Troubleshooting

policy-engine: command not found

Install the released binary and make sure it is on your PATH.

failed to read template ..., failed to read bytecode ..., or failed to read intent/evidence ...

Check that the path exists and points to the expected file type.

failed to parse intent JSON: ... or failed to parse evidence JSON: ...

The file is valid text but not valid JSON.

input validation error: ...

The JSON file parsed successfully, but the object does not match the template schema.

Source has unresolved Git merge conflict markers in this section

The upstream policy-engine/guides/cli-reference.md has unresolved conflict markers between bytecode hash mismatch: ... and template ID mismatch: .... Reproduced verbatim below; needs to be resolved in the source repo.

<<<<<<< fpoli/update-guides
> `bytecode hash mismatch: ...`
=======
`template ID mismatch: ...`
>>>>>>> main

The bytecode file does not match the template ID passed to --check-id.

print output does not match the original source file

This is expected. print renders the compiled template in a readable form, not an exact copy of the original source.