Skip to content

Latest commit

 

History

History
154 lines (100 loc) · 4.3 KB

cli-reference.md

File metadata and controls

154 lines (100 loc) · 4.3 KB

CLI Reference

CSL-Core provides a robust Command Line Interface (CLI) for compiling policies, verifying logic, and simulating runtime behavior.

The CLI is built with fail-safe defaults and rich visualization tools.

Installation & Usage

If installed via pip/poetry:

cslcore --help

Or running directly as a module:

python -m cslcore --help

1. Verify Command

cslcore verify <policy>

Parses the CSL policy, validates syntax, runs the Z3 Formal Verifier, and generates the compiled artifact.

  • Success: Prints policy metadata (Domain, Version, Hash) and confirms logical consistency.
  • Failure: Prints the specific logic error (Contradiction, Unreachable Rule, etc.) or syntax error.

Usage

# Standard verification (Recommended)
cslcore verify strict_policy.csl

# Debugging complex logic errors (Shows Z3 trace)
cslcore verify strict_policy.csl --debug-z3

Options

Flag Description
--debug-z3 Recommended for debugging. On failure, prints the internal Z3 trace tail to help diagnose sort mismatches or encoding issues.
--skip-verify Disables the Z3 logic check. Not recommended for production policies.
--skip-validate Skips semantic validation steps.

2. Simulate Command

cslcore simulate <policy>

Loads a compiled policy and runs the ChimeraGuard runtime against provided inputs. This mimics exactly how the policy will behave in your application code.

Input Methods

You can provide input as a raw JSON string or a file. The file can contain a single JSON object or a list of objects (batch mode).

# Single input via string
cslcore simulate policy.csl --input '{"action": "TRANSFER", "amount": 10000}'

# Batch input from file
cslcore simulate policy.csl --input-file execution_logs.json

Output Formats

By default, simulate prints human-readable tables using the Rich library.

# Visual Dashboard (Logic Gates & Audit Log)
cslcore simulate policy.csl --input-file test.json --dashboard

# Machine-Readable JSON (to stdout)
cslcore simulate policy.csl --input-file test.json --json --quiet

# JSON Lines (Append to file - good for pipelines)
cslcore simulate policy.csl --input-file test.json --json-out results.jsonl

Runtime Behavior Flags

CSL-Core is fail-closed by default. You can adjust this behavior using flags.

Flag Default Description
--dry-run False Analyzes input but never blocks. Reports what would have been blocked.
--fast-fail False Stops evaluation at the first violation. By default, it collects all violations for a full audit.
--no-raise False Prevents the CLI from exiting with an error code on BLOCK. Useful for batch processing.
--missing-key-behavior block What to do if a rule references a missing key: block, warn, or ignore.
--evaluation-error-behavior block What to do on type mismatches (e.g. comparing string to int): block, warn, or ignore.

3. REPL Command

cslcore repl <policy>

Starts an interactive Read-Eval-Print Loop. Useful for rapid prototyping and testing edge cases without reloading the policy file every time.

Usage

cslcore repl my_policy.csl --dashboard

Once inside:

cslcore> {"action": "deploy", "env": "prod"}
BLOCKED: Violation 'prod_freeze': env='prod' must be 'dev'.

cslcore> {"action": "deploy", "env": "dev"}
ALLOWED
  • Exit: Press Ctrl+C or enter an empty line.

Advanced Debugging

Z3 Trace (--debug-z3)

When a policy fails verification with an internal error or complex contradiction, standard error messages might not be enough.

Adding --debug-z3 enables the trace tail, which shows the last operations sent to the solver before the crash or contradiction.

Example Output:

Z3 Trace Tail
#   event            rule              data
1   register_var     limit             sort=Int
2   binop            GT                left=amount right=limit
3   INTERNAL_ERROR   ...               ...

Validation Codes

The CLI returns standard exit codes for CI/CD integration:

Code Meaning
0 Success / Allowed
2 Compilation/Verification Failed
3 Unexpected System Error
10 Runtime Blocked (Policy Violation)