CLI Reference

The @sidianlabs/policy CLI validates, checks, scaffolds, installs, and syncs POLICY.md files.

Note: the package is not published to npm yet. Until it is, run the CLI from a clone:

git clone https://github.com/SidianLabs/POLICY.md.git && cd POLICY.md
npm install && npm run build
node bin/policy.js --help

The examples below use npx @sidianlabs/policy — substitute node bin/policy.js (or a global install) until the package ships.

validate

npx @sidianlabs/policy validate examples/project/POLICY.md
npx @sidianlabs/policy validate examples/project/POLICY.md --strict

PolicyValidator checks required fields, valid operators, and YAML syntax. With --strict, unknown fields are rejected.

check

Evaluate a command against a policy without executing anything:

npx @sidianlabs/policy check examples/project command.run --payload='{"argv":"rm -rf /"}'

Usage: policy check <path> <capability> [--payload=<json>] [--agent=<id>]. Returns the decision (allow / deny / require_approval) and the rule that fired.

init

Bootstrap a POLICY.md for a project:

npx @sidianlabs/policy init my-project

Scaffolds a file with default rules: no secret-file writes, approval for new dependencies, tests allowed.

install

Pull reusable guardrails from any GitHub repo:

npx @sidianlabs/policy install SidianLabs/payment-guardrails --dest=.policies
npx @sidianlabs/policy install owner/repo

Policies become shareable artifacts - teams publish their guardrails, others install them.

list

List every policy discovered in the working directory:

npx @sidianlabs/policy list

sync

Regenerate the AGENTS.md <policy_system> block so agent runtimes pick up current policies:

npx @sidianlabs/policy sync

read

Read and print the effective policy for a directory:

npx @sidianlabs/policy read examples/project

Programmatic API

Everything the CLI does is available as a library:

import { createPolicyManager, buildPoliciesContext, createAuthorizationEngine } from '@sidianlabs/policy';

const manager = createPolicyManager();
manager.load(); // searches working dir for POLICY.md files

// Inject into an agent system prompt
const prompt = buildPoliciesContext(manager);

// Enforce at runtime
const engine = manager.createAuthorizationEngine();
const decision = engine.evaluate({
  id: '1',
  workRunId: 'run-1',
  workerId: 'agent-1',
  specialist: 'frontend',
  actionType: 'tool',
  capability: 'file.write',
  riskLevel: 'medium',
  payload: { path: 'src/.env' },
  requester: { type: 'user', id: 'user-1' },
  createdAt: Date.now(),
});

// decision.action === 'deny'

Compose with other policy sources

import { createCompositeAuthorizationEngine } from '@sidianlabs/policy';

const filePolicyEngine = manager.createAuthorizationEngine();
const orgPolicyEngine = createAuthorizationEngine({ document: orgPolicy });
const final = createCompositeAuthorizationEngine([orgPolicyEngine, filePolicyEngine]);

const result = final.evaluate(intent);

The composite engine returns the most severe decision across all engines (deny > require_approval > allow).

OpenAI Codex adapter

Convert policies to Codex execpolicy Starlark or Guardian prompt text:

import { toCodexExecpolicy, toCodexGuardianPrompt } from '@sidianlabs/policy/adapters/codex';

const execpolicy = toCodexExecpolicy(manager.list());
const guardianPrompt = toCodexGuardianPrompt(manager.list());