# pnpm (recommended)
pnpm add -g @i4ctime/q-ring

# npm
npm install -g @i4ctime/q-ring

# yarn
yarn global add @i4ctime/q-ring

# Homebrew (macOS / Linux)
brew install i4ctime/tap/qring

# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...

# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY

# 3️⃣ List all keys (values are never shown)
qring list

# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY

# 5️⃣ Run a full health scan
qring health

# Set environment-specific values
qring set API_KEY "sk-dev-123" --env dev
qring set API_KEY "sk-stg-456" --env staging
qring set API_KEY "sk-prod-789" --env prod

# Value resolves based on context
QRING_ENV=prod qring get API_KEY   # → sk-prod-789
QRING_ENV=dev  qring get API_KEY   # → sk-dev-123

# Inspect the quantum state
qring inspect API_KEY

# See what environment q-ring detects
qring env

# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json

# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600

# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"

# Health check shows decay status
qring health

# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50

# Detect anomalies (burst access, unusual hours, chain tampering)
qring audit --anomalies

# Verify audit chain integrity
qring audit:verify

# Export audit log
qring audit:export --format json --since 2026-03-01
qring audit:export --format csv --output audit-report.csv

qring generate                          # API key (default)
qring generate --format password -l 32  # Strong password
qring generate --format uuid            # UUID v4
qring generate --format token           # Base64url token
qring generate --format hex -l 64       # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY

# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP

# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1

# Read it (self-destructs after this read)
qring tunnel read tun_abc123

# List active tunnels
qring tunnel list

# Pack secrets (prompts for passphrase)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt

# On another machine: unpack (prompts for passphrase)
cat bundle.txt | qring teleport unpack

# Preview without importing
qring teleport unpack <bundle> --dry-run

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

# Execute a deployment script with secrets injected
qring exec -- npm run deploy

# Inject only specific tags
qring exec --tags backend -- node server.js

# Run with a restricted profile (blocks curl/wget/ssh, 30s timeout)
qring exec --profile restricted -- npm test

# Scan current directory
qring scan .

  ✗ src/db/connection.js:12
    Key:     DB_PASSWORD
    Entropy: 4.23
    Context: const DB_PASSWORD = "..."

qring set DB_USER "admin"
qring set DB_PASS "supersecret"
qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb"

# Resolves embedded templates automatically
qring get DB_URL 
# Output: postgres://admin:supersecret@localhost/mydb

# Mark a secret as requiring approval
qring set PROD_DB_URL "..." --requires-approval

# Temporarily grant MCP access for 1 hour with a reason
qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0"

# List all approvals with verification status
qring approvals

# Revoke an approval
qring approve PROD_DB_URL --revoke

# Store the STS role configuration
qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:role/AgentRole", "durationSeconds":3600}' --jit-provider aws-sts

# Resolving the secret automatically assumes the role and caches the temporary token
qring get AWS_TEMP_KEYS

# Human-readable summary
qring context

# JSON output (for MCP / programmatic use)
qring context --json

# Lint files for hardcoded secrets
qring lint src/config.ts src/db.ts

# Auto-fix: replace hardcoded values and store in q-ring
qring lint src/config.ts --fix

# Scan entire directory with auto-fix
qring scan . --fix

# Store a memory
qring remember last_rotation "Rotated STRIPE_KEY on 2026-03-21"

# Retrieve it
qring recall last_rotation

# List all memories
qring recall

# Forget
qring forget last_rotation

# Install the hook
qring hook:install

# Uninstall
qring hook:uninstall

qring analyze

# Create secrets for a new Stripe integration
qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment

# With a hook to restart the app on change
qring wizard myservice --hook-exec "pm2 restart app"

# View the active policy
qring policy

# JSON output
qring policy --json

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"],
      "maxTtlSeconds": 86400
    }
  }
}

# Run with the "restricted" profile (blocks curl, wget, ssh; 30s timeout)
qring exec --profile restricted -- npm test

# Run with the "ci" profile (5min timeout, allows network)
qring exec --profile ci -- npm run deploy

# Default: unrestricted
qring exec -- echo "hello"

# Verify the entire audit chain
qring audit:verify

# Export as JSON
qring audit:export --format json --since 2026-03-01

# Export as CSV
qring audit:export --format csv --output audit-report.csv

# Store a secret in team scope
qring set SHARED_API_KEY "sk-..." --team my-team

# Store in org scope
qring set ORG_LICENSE "lic-..." --org acme-corp

# Resolution cascades: project > team > org > global
qring get API_KEY --team my-team --org acme-corp

# Rotate via the detected provider
qring rotate STRIPE_KEY

# Force a specific provider
qring rotate API_KEY --provider openai

# Validate all secrets (CI mode)
qring ci:validate

# JSON output for pipeline parsing
qring ci:validate --json

# Start the agent
qring agent --interval 60 --verbose

# With auto-rotation of expired secrets
qring agent --auto-rotate

# Single scan (for CI/cron)
qring agent --once

# Open the dashboard (auto-launches your browser)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser
qring status --no-open

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/quantum_ring/dist/mcp.js"]
    }
  }
}

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/quantum_ring/dist/mcp.js"]
    }
  }
}

qring CLI ─────┐
               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘       │
                       ├── Envelope (quantum metadata)
                       ├── Scope Resolver (global / project / team / org)
                       ├── Collapse (env detection + branchMap globs)
                       ├── Observer (tamper-evident audit chain)
                       ├── Policy (governance-as-code engine)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness + rotation)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Exec (profile-restricted injection + redaction)
                       ├── Scan (codebase entropy heuristics)
                       ├── Provision (JIT ephemeral credentials)
                       ├── Approval (HMAC-verified zero-trust tokens)
                       ├── Context (safe redacted project view)
                       ├── Linter (secret-aware code scanning)
                       ├── Memory (encrypted agent persistence)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

{
  "env": "dev",
  "defaultEnv": "dev",
  "branchMap": {
    "main": "prod",
    "develop": "dev",
    "staging": "staging",
    "release/*": "staging",
    "feature/*": "dev"
  },
  "secrets": {
    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  },
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget"],
      "maxRuntimeSeconds": 60
    }
  }
}