q-ring

<div align="center">
  <img src="https://raw.githubusercontent.com/I4cTime/q-ring/main/assets/social-card-optimized.jpg" alt="q-ring — never paste an API key into .env again" width="100%" />
</div>

# q-ring

**OS keychain secrets for AI coding agents, over MCP.**

[![CI](https://img.shields.io/github/actions/workflow/status/I4cTime/q-ring/ci.yml?style=flat-square&label=CI)](https://github.com/I4cTime/q-ring/actions/workflows/ci.yml)
[![NPM Version](https://img.shields.io/npm/v/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@i4ctime/q-ring)
[![NPM Downloads](https://img.shields.io/npm/dm/@i4ctime/q-ring?style=flat-square&color=0ea5e9&label=downloads)](https://www.npmjs.com/package/@i4ctime/q-ring)
[![Docs](https://img.shields.io/badge/docs-website-0ea5e9?style=flat-square)](https://qring.i4c.studio/docs)
[![MCP Tools](https://img.shields.io/badge/MCP_tools-46-0ea5e9?style=flat-square)](https://glama.ai/mcp/servers/I4cTime/q-ring)
[![Smithery](https://img.shields.io/badge/smithery-i4ctime%2Fq--ring-0ea5e9?style=flat-square)](https://smithery.ai/servers/i4ctime/q-ring)
[![Cursor Directory](https://img.shields.io/badge/cursor_directory-q--ring-0ea5e9?style=flat-square)](https://cursor.directory/plugins/q-ring)
[![PulseMCP](https://img.shields.io/badge/pulsemcp-q--ring-0ea5e9?style=flat-square)](https://www.pulsemcp.com/servers/i4ctime-q-ring)
[![mcpservers.org](https://img.shields.io/badge/mcpservers.org-q--ring-0ea5e9?style=flat-square)](https://mcpservers.org/servers/i4ctime/q-ring)
[![License](https://img.shields.io/npm/l/@i4ctime/q-ring?style=flat-square&color=0ea5e9)](https://github.com/I4cTime/q-ring/blob/main/LICENSE)
[![Discord](https://img.shields.io/badge/discord-join%20the%20studio-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/5uEApw5uEz)
[![YouTube](https://img.shields.io/badge/youtube-%40qring__dev-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@qring_dev)
[![X](https://img.shields.io/badge/follow-%40i4c__studio-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/i4c_studio)

<a href="https://glama.ai/mcp/servers/I4cTime/q-ring">
  <img src="https://glama.ai/mcp/servers/I4cTime/q-ring/badges/card.svg" alt="q-ring MCP server" width="400" />
</a>

Stop pasting API keys into plain-text `.env` files or wrestling with clunky secret managers. **q-ring** securely anchors your credentials to your OS's native vault (macOS Keychain, Linux Secret Service, Windows Credential Vault) and supercharges them with mechanics from quantum physics.

> 📖 **[View the Official Documentation](https://qring.i4c.studio/docs)** for a complete CLI reference, MCP prompt cookbooks, and architecture details.

### Why q-ring?
- **Superposition:** Store one key with multiple states (dev/staging/prod) that collapse based on context.
- **Entanglement:** Link keys across projects so rotating one automatically updates them all.
- **Tunneling:** Create ephemeral, in-memory secrets that self-destruct after a set time or read count.
- **Teleportation:** Securely pack and share AES-256-GCM encrypted secret bundles.
- **Seamless AI Integration:** 46 built-in MCP tools for native use in **Cursor**, **Kiro**, and **Claude Code**.

## 🚀 Installation

q-ring is designed to be installed globally so it's available anywhere in your terminal. Pick your favorite package manager:

```bash
# 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
```

### Docker (MCP server)

The repo ships a `Dockerfile` that builds the MCP server and exposes it through [`mcp-proxy`](https://github.com/punkpeye/mcp-proxy) — useful for hosted MCP deployments (e.g. Glama) or keeping the server off the host entirely:

```bash
git clone https://github.com/I4cTime/q-ring.git
cd q-ring
docker build -t qring-mcp .
docker run --rm -p 8080:8080 qring-mcp
```

> Note: inside a container there is no OS keychain (GNOME Keyring / macOS Keychain), so this path is for the MCP protocol surface, ephemeral use, and CI experiments — not for durable local secret storage. For day-to-day use install the CLI natively via one of the package managers above.

## ⚡ Quick Start

```bash
# 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

# Something not working? Diagnose the install (keyring, audit, MCP wiring)
qring doctor

# Tab completion for your shell
qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish
```

## Quantum Features

### Superposition — One Key, Multiple Environments

A single secret can hold different values for dev, staging, and prod simultaneously. The correct value resolves based on your current context.

```bash
# 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
```

### Environment Promotion — Diff, Then Promote

Once a secret carries per-environment states, promotion replaces copy-paste: compare two environments key by key (statuses only, never values), then copy a value from one state to another. `diff` exits 1 on drift, so it doubles as a CI gate; `promote` refuses to overwrite a differing target unless you say so.

```bash
# What differs between staging and prod? (same / different / missing on one side)
qring diff staging prod

# Make prod match staging for one key (asks before overwriting a different value)
qring promote DATABASE_URL --from staging --to prod

# Non-interactive, e.g. in a release script
qring promote DATABASE_URL --from staging --to prod --force --json
```

MCP agents get the same two operations as `diff_environments` and `promote_secret`.

### Wavefunction Collapse — Smart Environment Detection

q-ring auto-detects your environment without explicit flags. Resolution order:

1. `--env` flag
2. `QRING_ENV` environment variable
3. `NODE_ENV` environment variable
4. Git branch heuristics (`main`/`master` → prod, `develop` → dev)
5. `.q-ring.json` project config
6. Default environment from the secret

```bash
# See what environment q-ring detects
qring env

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

### Quantum Decay — Secrets with TTL

Secrets can have a time-to-live. Expired secrets are blocked from reads. Stale secrets (75%+ lifetime) trigger warnings.

```bash
# 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
```

### Observer Effect — Audit Everything

Every secret read, write, and delete is logged with a tamper-evident hash chain. Access patterns are tracked for anomaly detection.

```bash
# 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
```

### Quantum Noise — Secret Generation

Generate cryptographically strong secrets in common formats.

```bash
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
```

### Entanglement — Linked Secrets

Link secrets across projects. When you rotate one, all entangled copies update automatically.

```bash
# 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
```

### Tunneling — Ephemeral Secrets

Create secrets that exist only in memory. They never touch disk. Optional TTL and max-read self-destruction.

```bash
# 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
```

### Teleportation — Encrypted Sharing

Pack secrets into AES-256-GCM encrypted bundles for secure transfer between machines. Two ways to lock a bundle:

- **Passphrase** (v1): keys derived with PBKDF2-HMAC-SHA512 (210 000 iterations); each bundle records its iteration count, so old bundles still unpack.
- **Recipients** (v2, 0.18): each teammate runs `qring teleport keygen` once and shares their recipient string (`qring1…`, an X25519 public key; the private half lives in their OS keyring). `pack --to` encrypts a fresh content key to every recipient — HKDF-SHA256 over an ephemeral X25519 agreement, AES-256-GCM throughout, `node:crypto` only — so nothing secret travels beside the bundle and nobody has to whisper a passphrase.

```bash
# Passphrase bundle (prompts)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
cat bundle.txt | qring teleport unpack

# Recipient bundle: teammates publish their recipient once…
qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
qring teleport identity          # print it again later

# …then you add