CLI, local dev & agents

npx @usekeyring/cli init    # policy file, .gitignore, AGENTS.md, Claude skill, .mcp.json
npx @usekeyring/cli dev     # local Keyring on http://localhost:4983 — console + /api/v1

keyring dev boots an embedded Postgres (PGlite, persisted in .keyring/), installs the native schema, mints a local root key, pushes keyring.policy.json, and opens the console. Save the policy file and it re-pushes. Other terminals' keyring … commands route through the running server automatically.

The local server speaks the hosted wire format, so the normal SDK works unchanged:

const keyring = new Keyring({ baseUrl: "http://localhost:4983", apiKey: process.env.KEYRING_SECRET_KEY! });

TargetsCopy Anchor Link

Every command resolves one target (first match wins):

The key comes from --key, KEYRING_SECRET_KEY or KEYRING_API_KEY (local mode uses .keyring/local.json). .env.local, .env.development.local and .env load automatically.

Your own Postgres (embedded mode)Copy Anchor Link

Like Better Auth, Keyring can live in your database with no hosted API in the request path:

DATABASE_URL=postgres://… npx @usekeyring/cli migrate     # idempotent; --print emits the SQL
DATABASE_URL=postgres://… npx @usekeyring/cli bootstrap   # workspace + root key → .env.local
npx @usekeyring/cli push

import { Pool } from "pg";
import { createKeyring } from "@usekeyring/sdk/postgres";

export const keyring = createKeyring({
  database: new Pool({ connectionString: process.env.DATABASE_URL }),
  apiKey: process.env.KEYRING_SECRET_KEY!,
});
await keyring.assert(user.id, "invoices.refund");

createKeyring has the same methods and result shapes as new Keyring(...). Any driver with query(text, values) works (pg, @neondatabase/serverless, PGlite). Each call is one SELECT keyring.api_*(); the key's SHA-256 is checked, and its scopes enforced, inside Postgres. Subject tokens and outbound webhook delivery stay hosted-only.

Policy as code: keyring.policy.jsonCopy Anchor Link

{
  "$schema": "https://usekeyring.dev/schema/policy.json",
  "actions": {
    "invoices.read": "Read invoices",
    "invoices.refund": { "name": "Refund invoices", "category": "Billing" }
  },
  "roles": {
    "viewer": ["invoices.read"],
    "finance": { "name": "Finance", "actions": ["invoices.*"] },
    "admin": ["*"]
  },
  "defaultRole": "viewer",
  "spaces": {
    "acme": { "name": "Acme", "actions": { "tickets.close": "Close tickets" }, "roles": { "agent": ["tickets.close"] } }
  }
}

• keyring push --dry-run validates the file (errors point at JSON paths) and prints the diff.
• keyring push is additive. --prune also deletes roles, actions and links the file dropped, and needs --yes when it would delete anything.
• keyring pull exports the live model, so changes made in the console come back into the file.
• keyring generate writes keyring.gen.ts with Action / Role / Space unions, so a typo'd slug fails to compile.

Command referenceCopy Anchor Link

Built for agentsCopy Anchor Link

• JSON by default when piped. Output is JSON whenever stdout isn't a TTY, or when --json is passed. Errors are { "ok": false, "error": { "code", "message", "hint" } }, and hint is the next command to run.
• Discoverable. keyring commands --json returns every command, argument, flag and exit code.
• Safe by construction. Destructive pushes need --yes. Every mutating command is idempotent. Secrets are redacted in whoami and doctor.
• In-repo context. keyring init writes a managed AGENTS.md block and a Claude Code skill, and registers npx -y @usekeyring/cli mcp so Claude Code, Cursor and VS Code agents get check_access, get_subject_access, grant_role and the other tools.

claude mcp add keyring -- npx -y @usekeyring/cli mcp