@keynv/cli 0.1.0-rc.22 → 0.1.0-rc.24

package/README.md

@@ -1,80 +1,88 @@
 # @keynv/cli
 
-> Runtime text-surface protection for AI coding workflows.
+> Self-hosted secrets vault for teams and AI-assisted development.
 
 [![npm](https://img.shields.io/npm/v/@keynv/cli?color=F59E0B)](https://www.npmjs.com/package/@keynv/cli)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/keynv-labs/keynv/blob/main/LICENSE)
 
-Your AI agent's transcripts, your shell history, and your terminal output are
-leaking secrets right now. `keynv` keeps them out, in real time, on your
-machine. No cloud, no re-architecting how you work.
-
-```text
-$ keynv doctor
-
-  !  zsh history                 5 likely secrets across 1 file
-  !  Claude Code transcripts     62,306 likely secrets across 73 files
-  ·  Cursor logs                 clean
-
-  Total: 62,311 likely secrets across 74 files.
-```
-
-`doctor`, `scrub`, `shell`, and `watch` are fully local — no account, no server,
-no network calls. Match previews are bounded to 3 characters; raw secret values
-never appear in output.
+Store your API keys, database URLs, and other secrets in one vault — hosted on
+[keynv.dev](https://keynv.dev) or self-hosted — and reference them everywhere by
+alias (`@project.env.key`) instead of the real value. `keynv` resolves aliases
+into your app at runtime, so the real values never touch your code, your shell
+history, or your AI agent's transcripts. Your agent sees
+`@billing.prod.stripe_key`, never the key itself.
 
 ## Install
 
 ```bash
 npm install -g @keynv/cli
-keynv doctor
 ```
 
-Prefer a standalone binary over Node? Every
+Node 20+. Prefer a standalone binary over Node? Every
 [release](https://github.com/keynv-labs/keynv/releases) publishes signed
 executables for macOS / Linux / Windows with a `SHA256SUMS` manifest.
 
 ## Quick start
 
-```bash
-# 1. Find out where you're leaking (scan only — nothing is rewritten)
-keynv doctor
+### Option A · Use keynv.dev (hosted — fastest)
 
-# 2. Clean what's already there (atomic, with backups; --dry-run to preview)
-keynv scrub --dry-run
-keynv scrub
+1. Create a free account at [keynv.dev/register](https://keynv.dev/register).
+2. Connect and set up your project:
 
-# 3. Prevent new leaks — a marked hook in your ~/.zshrc / ~/.bashrc / fish
-keynv shell install
-keynv shell status
+   ```bash
+   keynv                       # pick "keynv.dev", then "Set up this project"
+   ```
 
-# 4. Real-time watcher over Claude Code transcripts + Cursor logs
-keynv watch start
-keynv watch status
-```
+### Option B · Self-host
 
-The shell hook scrubs secret-shaped substrings before each command lands in
-history (POSIX-ERE, no per-command subprocess unless a match fires). The watcher
-subscribes to `~/.claude/projects/**/*.jsonl` and Cursor logs via chokidar,
-debounces at 1 second, and atomically rewrites matched substrings.
+Run your own server + panel in ~15 minutes — see the
+[Coolify walkthrough](https://github.com/keynv-labs/keynv/blob/main/deploy/COOLIFY.md)
+or [Docker Compose guide](https://github.com/keynv-labs/keynv/blob/main/deploy/README.md).
+Then run `keynv`, choose **Self-hosted server**, and enter your API URL.
 
-## Aliases (optional — needs a server)
+> On a headless Linux box with no OS keychain (no libsecret), set
+> `KEYNV_DISABLE_KEYCHAIN=1` before connecting — credentials then persist to an
+> encrypted file instead of the system keychain.
 
-For the "AI agents never see real values" workflow, `keynv` stores secrets in a
-vault and hands out aliases (`@project.env.KEY`) instead of values. This needs a
-keynv server — self-host in ~15 minutes with the
-[Coolify walkthrough](https://github.com/keynv-labs/keynv/blob/main/deploy/COOLIFY.md)
-or [Docker Compose](https://github.com/keynv-labs/keynv/blob/main/deploy/README.md).
+### Then run your app — the way you already do
+
+Setup imports your existing `.env` files into the vault and writes a committable
+`.keynv.env` that maps your environment variables to aliases. It also wraps your
+`package.json` scripts, so you just run them normally:
 
 ```bash
-keynv login                    # browser flow; session lands in the OS keychain
-keynv project create demo
-keynv secret create @demo.dev.api_key --value 'whatever'
-keynv exec -- npm run dev      # aliases resolved into the child, redacted from output
+npm run dev                    # secrets injected automatically — no `keynv exec` to type
+npm test
 ```
 
-Running `keynv` with no arguments opens an interactive TUI that walks through the
-same operations.
+`.keynv.env` is safe to commit — it holds references, not values:
+
+```bash
+OPENAI_API_KEY=@myapp.dev.openai-key
+DATABASE_URL=@myapp.prod.db-url
+NODE_ENV=development           # plain literals pass through unchanged
+```
+
+Behind the scenes your wrapped script runs `keynv exec -- <your command>`, which
+resolves each `@alias` against the vault and forks your command with the real
+values in a subprocess your editor and AI agent can't read — redacting them from
+output. **You never type `keynv exec` yourself.**
+
+Teams get project-scoped roles (owner / admin / developer / reader), per-secret
+access, rotation, and a tamper-evident audit log — all managed from the CLI or
+the web panel.
+
+## Common commands
+
+```bash
+keynv                          # interactive TUI (projects, secrets, members)
+keynv secret create            # add a secret to the vault
+keynv secret get @a.dev.key --copy   # copy a value to the clipboard without printing it
+keynv exec -- <cmd>            # run a one-off command with aliases resolved
+keynv member list <project>    # who has access to a project
+keynv whoami                   # who am I logged in as
+keynv --help                   # full command list
+```
 
 ## Use with Claude Code / Cursor (MCP)
 
@@ -83,11 +91,25 @@ never see the value. See the
 [AI setup guide](https://github.com/keynv-labs/keynv/blob/main/docs/ai-setup.md)
 for wiring it into Claude Code, Cursor, and other MCP clients.
 
+## Also: clean up leaks you already have
+
+Secrets already sitting in your shell history or AI transcripts? These commands
+run entirely locally — no server or login needed:
+
+```bash
+keynv doctor                   # scan for leaked secrets (read-only, no network)
+keynv scrub                    # clean them up, atomically, with backups
+keynv watch start              # scrub live AI-agent sessions in real time
+```
+
+Match previews are bounded to 3 characters; raw secret values never appear in
+output.
+
 ## Documentation
 
 - [Getting started](https://github.com/keynv-labs/keynv/blob/main/docs/getting-started.md)
 - [AI setup (Claude Code / Cursor / MCP)](https://github.com/keynv-labs/keynv/blob/main/docs/ai-setup.md)
-- [What keynv is — and is not](https://github.com/keynv-labs/keynv/blob/main/docs/00-vision.md)
+- [Coolify deploy](https://github.com/keynv-labs/keynv/blob/main/deploy/COOLIFY.md)
 - [Threat model](https://github.com/keynv-labs/keynv/blob/main/docs/02-threat-model.md)
 - [Full README](https://github.com/keynv-labs/keynv#readme)