CLI reference

policyglass check

Validate a directory tree against a policy file.

policyglass check TARGET --policy POLICY [--format text|json]

Arguments

• TARGET: directory to scan

Options

• --policy: YAML policy file to load
• --format: output mode; one of text or json

Behavior

• resolves both target and policy to absolute paths before running
• exits with 0 for a passing report, 1 for a report with findings, and 2 for invocation, policy-loading, or operational scan errors
• prints a concise text report by default
• prints structured JSON when --format json is used
• writes operational errors only to standard error without a traceback; JSON-mode errors leave standard output empty rather than emitting a partial or alternate JSON document
• scans every file under the target tree, including the policy file itself if it lives under the target

policyglass init

Write a starter policy file.

policyglass init DESTINATION [--force]

Arguments

• DESTINATION: file path to create

Options

• --force: overwrite an existing file

Behavior

• creates parent directories automatically
• refuses to overwrite an existing file unless --force is provided

Output shape

Text

Text output escapes non-printable characters in roots, finding paths, and messages so each record stays on one terminal line. Printable Unicode remains readable; non-printable Unicode is shown with Python-style escapes (\n, \x1b, \u202e, or \U000e0001), and literal backslashes are doubled so escaped and literal text remain distinguishable.

FAIL /repo
Scanned files: 3
Findings:
- forbidden_glob: secrets.pem — Path matches forbidden glob: *.pem

JSON

{
  "root": "/repo",
  "passed": false,
  "scanned_file_count": 3,
  "findings": [
    {
      "code": "forbidden_glob",
      "path": "secrets.pem",
      "message": "Path matches forbidden glob: *.pem"
    }
  ]
}