Documentation

Quick start

npx guardrails-ref init

Creates .agents/guardrails/, adds no-plaintext-secrets, configures Cursor, Claude Code, VS Code Copilot, Windsurf, Continue, and JetBrains.

Use init --preset default to add the default preset (4 guardrails) instead of one.
Use init --user for ~/.agents/guardrails/ (user-level). Use init --dry-run to preview without writing.

Run npx guardrails-ref setup so the AI reads your guardrails. Required until IDEs add native support.

Add more

npx guardrails-ref add no-destructive-commands

add --preset default, security, quality, frontend, api, backend, data, production.

Combine: add --preset default,frontend.

40 reference guardrails with descriptions and add commands.

Run npx guardrails-ref add --list to list available guardrails.

Commands

Scripting & CI

For pipelines and tooling:

npx guardrails-ref add --dry-run no-destructive-commands

Preview what would be added without writing files.

npx guardrails-ref list . --compact | xargs -I {} npx guardrails-ref why {}

One name per line for piping. Combine with why to inspect each.

npx guardrails-ref why no-plaintext-secrets --json

Machine-readable output (name, description, body) for tooling.

npx guardrails-ref setup --check --fail-if-missing

Exit 1 if configured IDE lacks the guardrail rule (CI enforcement).

GUARDRAILS_REF_READONLY=1 npx guardrails-ref validate --fix

Global read-only mode: behave as if --dry-run is enabled for write-capable commands.

npx guardrails-ref test . --json

Machine-readable safety check: verify guardrails are present (including rate-limiting and tools-permissions), plus scorePercent and attackCoverage.

npx guardrails-ref health . --json

One JSON for dashboards: IDE setup status + guardrails validation + safety test summary.

npx guardrails-ref drift . --json

Detect drift between installed guardrails and templates (great for CI gating).

npx guardrails-ref snapshot . --out guardrails-snapshot.json

Write an audit artifact (hashes + effective policy + current safety score) as a CI artifact.

npx guardrails-ref attack-test --target http://localhost:4000 --suite-file .guardrails-attack-suite.json --json

Run a customizable adversarial suite against your agent HTTP endpoint (JSON suite file + JSON output).

npx guardrails-ref test . --min-score 80 --require-categories secrets,destructive,prompt --require-guardrails no-plaintext-secrets,no-destructive-commands,no-prompt-leaks,tools-permissions

Enforce minimum safety score, required categories, and required guardrails in CI using a single command.

npx guardrails-ref suggest-pack . --json

Generate a suggested combination of presets and a starter .guardrails-ref.json for onboarding new repos; pipe the JSON into CI or tooling.

Profiles & Policy

Create a .guardrails-ref.json at the project root to configure policy, thresholds, and required guardrails:

{
  "test": { "minScorePercent": 70, "requireCategories": ["secrets"] },
  "profiles": {
    "ci": { "test": { "minScorePercent": 90 } },
    "dev": { "test": { "minScorePercent": 50 } }
  }
}

Activate a profile with --profile ci or the GUARDRAILS_REF_PROFILE env variable. Merge order: base config → profile overlay → CLI flags.

Supported by validate, check, test, health, drift, and snapshot.

Use extends to inherit from shared policy packs:

{
  "extends": ["./shared-policy"],
  "test": { "minScorePercent": 85 }
}

More

README · Examples · Pre-commit · npm · guardrails-ref presets · .guardrails-ref.json for project policy