kt policy lint

Validate a policy configuration file against the Keeptrusts schema. Linting checks for structural errors, unknown policy kinds, invalid fields, and logical contradictions.

Use this page when

• You need to validate a policy-config.yaml against the Keeptrusts schema before deploying.
• You want to integrate policy validation into a CI pipeline as a pre-merge gate.
• You see lint errors and need to understand error codes (E001–E003) and suggested fixes.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Usage

kt policy lint --file <path>

Options

Flag	Description
--file <path>	Path to the policy configuration YAML file
--json	Output validation results as JSON

Examples

Valid Configuration

kt policy lint --file policy-config.yaml

OK policy-config.yaml is valid
  Pack: production (v0.2.0)
  Chain: prompt-injection -> pii-detector -> audit-logger
  Policies validated: 3

JSON Output

kt policy lint --file policy-config.yaml --json

{
  "valid": true,
  "file": "policy-config.yaml",
  "pack": {
    "name": "production",
    "version": "0.2.0"
  },
  "chain": ["prompt-injection", "pii-detector", "audit-logger"],
  "policy_count": 3,
  "warnings": []
}

Invalid Configuration

kt policy lint --file bad-config.yaml

X bad-config.yaml has 3 errors

  error[E001]: Unknown policy kind 'prompt-injections'
    --> policies.chain[0]
    help: Did you mean 'prompt-injection'?

  error[E002]: Unknown key 'actions' in policy.pii-detector
    --> policy.pii-detector.actions
    help: Valid keys are: action, healthcare_mode, pci_mode, redaction

  error[E003]: Policy 'quality-scorer' is in chain but has no config block
    --> policies.chain[2]
    help: Add a 'policy.quality-scorer' section or remove from chain

Exit code 2 on validation failure.

JSON Error Output

kt policy lint --file bad-config.yaml --json

{
  "valid": false,
  "file": "bad-config.yaml",
  "errors": [
    {
      "code": "E001",
      "path": "policies.chain[0]",
      "message": "Unknown policy kind 'prompt-injections'",
      "suggestion": "Did you mean 'prompt-injection'?"
    },
    {
      "code": "E002",
      "path": "policy.pii-detector.actions",
      "message": "Unknown key 'actions' in policy.pii-detector",
      "suggestion": "Valid keys are: action, healthcare_mode, pci_mode, redaction"
    }
  ]
}

What Lint Checks

Check	Description
Schema validation	YAML parses correctly and matches expected structure
Unknown top-level keys	Only pack, policies, policy, providers allowed
Unknown policy kinds	Every kind in chain must be recognized
Unknown fields	Keys inside policy.<kind> must match schema
Missing required fields	pack.name, pack.version, pack.enabled, policies.chain
Empty chain	policies.chain must have at least one entry
Provider contradictions	ZDR settings that would exclude all providers
Unused policy blocks	Config defines policy.<kind> not referenced in chain (warning)

Example Configurations

Minimal Valid Config

pack:
  name: "my-project"
  version: "0.1.0"
  enabled: true

policies:
  chain:
    - prompt-injection

Full Config with Policy Details

pack:
  name: "production"
  version: "0.2.0"
  enabled: true
  description: "Production policy enforcement"

policies:
  chain:
    - prompt-injection
    - pii-detector
    - quality-scorer
    - audit-logger

policy:
  prompt-injection:
    threshold: 0.8
    action: "block"

  pii-detector:
    action: "redact"
    healthcare_mode: false
    pci_mode: true
    redaction:
      marker_format: "label"
      include_metadata: true
      preserve_length: false

  quality-scorer:
    min_score: 0.7
    assertions:
      - type: "model-graded-closedqa"
        threshold: 0.8

  audit-logger:
    retention_days: 365

For AI systems

• Canonical command: kt policy lint --file <path>.
• Flags: --file, --json.
• Error codes: E001 (unknown policy kind), E002 (unknown field), E003 (missing config block).
• Checks: schema validation, unknown top-level keys, unknown policy kinds, unknown fields, missing required fields, empty chain, provider contradictions, unused policy blocks.
• Exit codes: 0 = valid, 2 = validation failure.
• Related pages: kt policy test, kt gateway run, Config-First Workflow.

For engineers

• Prerequisites: A policy-config.yaml file. No API connectivity needed — lint runs entirely offline.
• CI usage: kt policy lint --file policy-config.yaml --json returns structured output; check exit code 2 in CI to fail the build.
• Troubleshooting: E001 often means a typo in the policy kind name — check the help: Did you mean ...? suggestion. E002 means an invalid key inside a policy block — compare with the schema reference.
• Combine with kt policy test to validate both structure and runtime behavior before rollout.

For leaders

• kt policy lint is the first quality gate in the policy delivery pipeline — it catches structural errors before any traffic is affected.
• Adding kt policy lint to CI/CD prevents misconfigured policies from being merged, reducing the risk of production incidents.
• Zero runtime cost: lint is a local, offline check with no API calls or provider dependencies.

Next steps

• kt policy test — Run behavioral tests against your policy chain
• kt gateway run — Start the gateway with a validated config
• Config-First Workflow — The recommended policy-as-code lifecycle
• CLI overview