Documentation
Quick start
npx guardrails-ref initCreates .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).
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-commandsOr add a preset: add --preset default, security, quality, frontend, api, or production. Combine with commas: add --preset default,frontend.
30 reference guardrails with descriptions and add commands.
Run npx guardrails-ref add --list to list available guardrails.
Commands
| Command | Description |
|---|---|
init | Create dir, add example, run setup |
init --preset default | Add preset instead of single example |
init --minimal | Create .agents/guardrails/ only (no example, no setup) |
add <name> | Add guardrail(s) |
add --dry-run | Preview what would be added without writing |
add --preset default | Add default preset (4 guardrails) |
add --preset default,frontend | Add multiple presets (comma-separated) |
add --preset security | Add security preset (9 guardrails) |
add --preset quality | Add quality preset (8 guardrails) |
add --preset frontend | Add frontend preset (3 guardrails) |
add --preset api | Add API preset (4 guardrails) |
add --preset production | Add production preset (6 guardrails) |
remove <name> | Remove guardrail |
setup | Add rule to Cursor, Claude Code, Copilot, Windsurf, Continue, JetBrains |
setup --remove | Undo setup |
setup --pre-commit | Add guardrails check to pre-commit (Husky or pre-commit) |
setup --ide <name> | Target IDE: cursor, claude, copilot, windsurf, continue, jetbrains, junie, or auto |
setup --dry-run | Preview what would be added/removed |
setup --check | Show which IDEs are configured |
setup --check --fail-if-missing | Exit 1 if configured IDE lacks rule (CI) |
validate | Validate files |
validate --fix | Apply fixes (whitespace, newline, frontmatter key order) |
validate --user | Validate user-level guardrails |
validate --json | JSON output for scripting |
validate --strict | Fail on warnings (CI) |
check | Minimal CI output |
upgrade | Update to latest templates |
upgrade --user | Upgrade user-level guardrails |
upgrade --dry-run | Preview changes |
diff | Show diff between installed and templates |
list | List guardrails |
list --user | List user-level guardrails |
list --json | JSON output for scripting |
list --compact | One name per line (for piping) |
why <name> | Show guardrail template content |
why <name> --json | JSON output (name, description, body) |
Scripting & CI
For pipelines and tooling:
npx guardrails-ref add --dry-run no-destructive-commandsPreview 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 --jsonMachine-readable output (name, description, body) for tooling.
npx guardrails-ref setup --check --fail-if-missingExit 1 if configured IDE lacks the guardrail rule (CI enforcement).
More
README · Examples · Pre-commit · npm