keyshroud 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.5.3] - 2026-10-15
+
+### Security
+Fixes from an independent audit and a multi-model review of 0.5.2.
+- The native dialog could be used by a prompt-injected agent to phish new
+  secrets, including the vault master password. It now says a program asked for
+  it and warns against the master password, refuses multi-line, control or bidi
+  characters and names over 120 characters, refuses a value equal to the master
+  password, opens one at a time with a 30 s pause after a cancel, and is audited.
+  zenity runs with `--no-markup`.
+- Env files could set `PATH`, `NODE_OPTIONS`, `LD_PRELOAD` and other loader
+  variables, so a cloned repo's `.env.refs` could run code. They are rejected
+  in env files, refused by `add`/`wire`/`secrets_request`, and never injected.
+- Streaming redaction leaked most of a secret longer than 4096 characters.
+- `secrets_run` could return a partial secret when output hit the collection
+  limit; the cut tail is now dropped before masking, with per-stream budgets.
+- `import` missed `*_PASS`, URL passwords with no username, hex keys, and known
+  key formats in names containing `PUBLIC`; `.env.refs` is now written `0600`.
+- `inject -o` replaces a planted symlink instead of writing through it; temp
+  files use random names and exclusive creation.
+
+### Changed
+- `add`/`rotate` read stdin only with `--stdin`; a multi-line paste into the
+  `*` prompt is drained and refused instead of reaching the shell.
+- `secrets_request` checks names and existing items before opening the dialog,
+  reports auth.json conflicts instead of claiming success, and returns errors.
+- Item names with leading or trailing spaces are refused (they shadowed
+  existing items). `add`, `rotate` and `secrets_request` refresh the redact
+  index and write to the audit log.
+
+## [0.5.2] - 2026-10-15
+
+### Added
+- `keyshroud import`: moves the secrets in a `.env` into the vault and writes
+  `.env.refs`. Dry run with names only by default, `--yes` to write; values are
+  verified after storing, never printed, and `--replace` rewrites the source
+  atomically without a backup.
+
+- `add`/`rotate` without a terminal, and the `secrets_request` MCP tool, open a
+  native hidden-input dialog (macOS `osascript`, Linux `zenity`/`kdialog`), so
+  an agent can start the command and the user only pastes. `--dialog` forces it.
+
+### Changed
+- The `add` and `rotate` prompts echo `*` per character (a count after 24) so
+  typing and pastes are visible without showing the value; Backspace, Ctrl-U
+  and Ctrl-C work as in a password prompt.
+
 ## [0.5.1] - 2026-10-14
 
 ### Added

package/README.md

@@ -19,7 +19,7 @@ secrets stay in your own self-hosted [Vaultwarden](https://github.com/dani-garci
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/node/v/keyshroud.svg)](package.json)
 
-[🚀 Quickstart](#quickstart) · [🔌 Supported agents](#supported-agents) · [⚙️ How it works](#how-it-works) · [❓ FAQ](#faq) · [🛡️ Security model](#security-model) · [🌐 Website](https://keyshroud.dev)
+[🚀 Quickstart](#quickstart) · [🔐 Vault setup](examples/vaultwarden#readme) · [🔌 Supported agents](#supported-agents) · [⚙️ How it works](#how-it-works) · [❓ FAQ](#faq) · [🛡️ Security model](#security-model) · [🌐 Website](https://keyshroud.dev)
 
 [🇻🇳 Tiếng Việt](i18n/README.vi.md) · [🇨🇳 简体中文](i18n/README.zh-CN.md) · [🇯🇵 日本語](i18n/README.ja-JP.md)
 
@@ -61,7 +61,7 @@ webhooks, databases. The usual options are bad:
 | 🙈 **Masked output** | `keyshroud run` replaces every secret value in stdout/stderr with `<redacted:NAME>` — streaming-safe across chunk boundaries. |
 | 🪝 **Agent hooks** | The pi/omp `tool_result` hook redacts every tool result, failed ones included. Claude Code's `PostToolUse` hook redacts every *successful* tool result (Bash, Read, Grep, MCP…) — see [limits](#security-model). |
 | 🔌 **MCP server** | `keyshroud mcp` gives any MCP client `secrets_run`, `secrets_list`, `secrets_request`, `vault_status`. No tool ever returns a value. |
-| 🔗 **Commit-safe references** | `bw://item`, `bw://item/username`, `bw://item/fields/name`, `bw://item/totp` in `.env.refs` files and templates. |
+| 🔗 **Committable references** | `bw://item`, `bw://item/username`, `bw://item/fields/name`, `bw://item/totp` in `.env.refs` files and templates: names, not values. |
 | ⌨️ **Paste-to-create** | New secrets go through a masked prompt in the user's terminal or a masked popup in pi — never through the chat. |
 | 📄 **`inject`** | Render `{{ bw://… }}` templates into `0600` config files for tools that can't read env vars (`.npmrc`, kubeconfig). |
 | 🔎 **`scan`** | Find vault values that leaked into your working tree (pre-commit friendly). |
@@ -82,9 +82,9 @@ webhooks, databases. The usual options are bad:
 
 ## Use cases
 
-**"Claude Code keeps reading my `.env`."** Move the values into the vault, commit a
-`.env.refs` file with `GH_TOKEN=bw://GitHub CLI token`, and start the agent with
-`keyshroud run -- claude`. The plugin's hooks mask anything that still slips into a tool result.
+**"Claude Code keeps reading my `.env`."** Run `keyshroud import` to move the values into
+the vault and write a `.env.refs` file with lines like `GH_TOKEN=bw://myapp GH_TOKEN`, then start
+the agent with `keyshroud run --env-file .env.refs -- claude`. The plugin's hooks mask anything that still slips into a tool result.
 
 **"I already self-host Vaultwarden."** Point `bw` at it, run `keyshroud doctor`, and you
 are done — keyshroud adds no server of its own.
@@ -92,18 +92,24 @@ are done — keyshroud adds no server of its own.
 **"I like `op run` but don't want 1Password."** `keyshroud run` is the same idea —
 references in, masked output out — on a vault you host.
 
-**"My agent needs to add a new key."** It calls `secrets_request` (MCP) or `/secret` (pi);
-you type the value into a masked prompt in your own terminal. It never enters the chat.
+**"My agent needs to add a new key."** It runs `keyshroud add` or calls `secrets_request` (MCP),
+and a hidden-input dialog pops up on your desktop; in pi it is `/secret`. You paste the value
+there. It never enters the chat.
 
 ## Quickstart
 
-**Requirements:** Node.js ≥ 22.18, the Bitwarden CLI (`npm i -g @bitwarden/cli`),
-and a Vaultwarden or Bitwarden account. No server yet?
-[examples/vaultwarden](examples/vaultwarden) runs Vaultwarden behind Caddy
-(automatic HTTPS) with one `docker compose up -d`.
+**Requirements:** Node.js ≥ 22.18, the Bitwarden CLI, and a vault.
+
+**0. Get a vault** — pick one:
+
+- **Self-host Vaultwarden** (free, your server): follow
+  [examples/vaultwarden](examples/vaultwarden#readme) — Docker Compose + Caddy with automatic HTTPS,
+  from an empty VPS to `keyshroud doctor`, plus backups and hardening.
+- **Bitwarden cloud** (free account, no server): sign up at [bitwarden.com](https://bitwarden.com)
+  and skip `bw config server` below (EU accounts: `bw config server https://vault.bitwarden.eu`).
 
 ```bash
-npm install -g keyshroud
+npm install -g keyshroud @bitwarden/cli    # or: brew install bitwarden-cli
 
 # 1. Point bw at your server and log in once
 bw config server https://vault.example.com
@@ -126,7 +132,8 @@ keyshroud run -- claude          # start an agent with every wired secret availa
 
 Optional: put `vaultwarden-api-client-id` / `vaultwarden-api-client-secret` (from
 *Settings → Security → Keys → API key*) in the keychain too, and keyshroud will
-also re-login automatically when the `bw` session expires.
+also re-login automatically when the `bw` session expires. Linux keyring commands
+and a headless-server option are in the [vault setup guide](examples/vaultwarden#4-let-keyshroud-unlock-without-prompting).
 
 ## How it works
 
@@ -250,7 +257,7 @@ OpenCode: `opencode mcp add keyshroud -- keyshroud mcp`.
 |---|---|---|
 | `secrets_list` | Lists wired names (+ optional `env_file`) | resolved / unresolved names |
 | `secrets_run` | Runs a shell command with secrets injected (`only`, `env_file`, `cwd`, `timeout_ms`) | exit code + masked stdout/stderr |
-| `secrets_request` | Asks the human to store a new secret | a `keyshroud add …` command for *their* terminal |
+| `secrets_request` | Opens a hidden-input dialog on the user's desktop and stores the value | `created … verified=yes`, or a `keyshroud add …` command for *their* terminal when no dialog can be shown |
 | `vault_status` | Vault lock state, server, item count | status line |
 
 ## CLI reference
@@ -262,8 +269,9 @@ keyshroud inject [-i template] [-o out] [--force]
 keyshroud redact < log.txt
 keyshroud scan [paths...]
 keyshroud env [--shell]
-keyshroud add --env NAME --item ITEM [--notes TEXT] [--target pi|omp|both] [--stdin]
-keyshroud rotate --item ITEM [--stdin]
+keyshroud add --env NAME --item ITEM [--notes TEXT] [--target pi|omp|both] [--stdin|--dialog]
+keyshroud import [--from F|-] [--out F] [--prefix P] [--only A,B] [--skip A,B] [--yes] [--replace] [--force]
+keyshroud rotate --item ITEM [--stdin|--dialog]
 keyshroud wire --env NAME --item ITEM [--target pi|omp|both] [--force]
 keyshroud unwire --env NAME [--target pi|omp|both]
 keyshroud status | unlock | lock | doctor
@@ -278,6 +286,27 @@ keyshroud link-cli [--dir DIR] [--force]
 passes the TTY through untouched for interactive use. Force either way with
 `--mask` / `--no-mask`. `exec` is an alias of `run`.
 
+`add` and `rotate` read the value from a masked prompt that shows `*` per
+character. Without a terminal (an agent's shell), they open a native hidden-input
+dialog instead (`osascript` on macOS, `zenity` or `kdialog` on Linux), so the agent
+can start the command and you only paste. Over SSH or without a display, pipe the
+value with `--stdin`.
+
+`import` reads a `.env` (default `./.env`), decides which lines are secrets (by name, such as
+`*_TOKEN` or `*_KEY`, or by value, such as `sk-…` or a URL with a password), and prints a plan of
+names only. Nothing is written until you add `--yes`: it then creates one vault item per secret,
+named `<prefix> NAME` (prefix defaults to the directory name), reads each value back to verify it,
+and writes `.env.refs` with comments and non-secret lines kept. Re-running reuses items that already
+hold the same value and stops on a conflicting one. `--replace` rewrites the source file in place
+instead (atomically, no backup copy). Multiline values, `${VAR}` expansion and duplicate keys are
+rejected with the line number, never the value.
+
+```bash
+keyshroud import                 # dry run: which names would move
+keyshroud import --yes           # store them and write .env.refs
+keyshroud run --env-file .env.refs -- npm test
+```
+
 **Exit codes:** `0` ok · `2` usage · `3` vault locked or unavailable · `4` secret
 missing or item name ambiguous · `5` refusing to overwrite existing state.
 `run` exits with the child's code.
@@ -344,18 +373,30 @@ Guarantees we test for:
 
 - secret values never appear in argv, logs, diagnostics, MCP results, hook
   output, or `audit.jsonl`;
-- new secrets are read from a masked prompt or stdin, never flags;
+- new secrets are read from a masked prompt, `--stdin`, or a native dialog, never flags;
+- the dialog an agent can open says it was requested by a program, warns against the
+  master password, refuses names that are not one printable line, refuses the master
+  password itself, and opens one at a time (30 s pause after a cancel);
 - the session file, redact index, rendered templates and auth files are `0600`;
 - auth.json writes are locked and atomic and never overwrite without `--force`;
 - commands started by `run` and `secrets_run` never receive `BW_SESSION`,
   `BW_PASSWORD`, `BW_CLIENTID` or `BW_CLIENTSECRET`, so `--only` really limits
   what a command can read (inside pi/omp the agent process keeps the session for
   legacy `!bw` auth entries; its value is redacted from tool output);
-- env files may contain only references and literals — a `!command` value is
-  rejected, so a cloned repo's `.env.refs` cannot run code;
+- env files may contain only references and literals: a `!command` value is
+  rejected, and so are variables that change what programs load or run (`PATH`,
+  `NODE_OPTIONS`, `LD_*`, `DYLD_*`, `BASH_ENV`, `GIT_SSH_COMMAND`, …), which are
+  also never wired or injected;
 - an unparseable `auth.json` is never overwritten.
 
-Known limits: an agent with shell access as your user can read
+Known limits: a `.env.refs` can reference **any** item in your vault, not only the
+ones you wired, so read a cloned repo's `.env.refs` before running `--env-file`
+with it. `import` decides what is secret by heuristics and keeps everything else
+as a literal; check its plan before committing `.env.refs`. The Claude Code
+`PostToolUse` hook does not see failed commands (`PostToolUseFailure` cannot
+rewrite output) or anything a client sends as telemetry, and it only knows wired
+values, so `keyshroud get bw://…` or `run --no-mask` print in the clear; run
+secret-using commands through `keyshroud run` or `secrets_run`. An agent with shell access as your user can read
 `~/.config/keyshroud/session` and use `bw` directly — run agents in a sandbox or
 container if that matters. Redaction is exact-match, so a *partial* or transformed value
 (`${TOKEN:0:10}`, base64, a line wrapped by a tool) is not masked; values

package/dist/cli.js

@@ -1,16 +1,17 @@
 #!/usr/bin/env node
-import { chmod, copyFile, mkdir, lstat, readdir, readFile, readlink, symlink, unlink, writeFile } from "node:fs/promises";
+import { chmod, copyFile, mkdir, lstat, readdir, readFile, readlink, rename, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { constants, homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import process from "node:process";
 import { BRAND } from "./brand.js";
 import * as core from "./core.js";
 import { runClaudeHook } from "./hooks.js";
 import { serveMcp } from "./mcp.js";
 import { buildRedactIndex, compileRedactIndex, createRedactor, createRedactStream } from "./redact.js";
-import { ENV_NAME_RE, parseRef } from "./refs.js";
+import { ENV_NAME_RE, isLoaderEnvName, isRef, itemNameProblem, looksSecret, parseDotenvStrict, parseRef } from "./refs.js";
 const usage = `Usage: ${BRAND.bin} <command> [options]
 
 Secrets
@@ -21,8 +22,11 @@ Secrets
   redact                           Copy stdin to stdout with vault secrets masked
   scan [paths...]                  Find vault secret values in files (exit 1 on leaks)
   env [--shell]                    List wired names (or print shell exports)
-  add --env NAME --item ITEM [--notes TEXT] [--target pi|omp|both] [--stdin]
-  rotate --item ITEM [--stdin]
+  add --env NAME --item ITEM [--notes TEXT] [--target pi|omp|both] [--stdin|--dialog]
+  import [--from F|-] [--out F] [--prefix P] [--only A,B] [--skip A,B] [--yes] [--replace] [--force]
+                                   Move secrets from a .env into the vault and write .env.refs
+                                   (dry run unless --yes; prints names only)
+  rotate --item ITEM [--stdin|--dialog]
   wire --env NAME --item ITEM [--target pi|omp|both] [--force]
   unwire --env NAME [--target pi|omp|both]
 
@@ -60,6 +64,27 @@ function targetList(value) {
         return [targetPaths.pi];
     fail("--target must be omp, pi, or both", 2);
 }
+// --stdin: piped value. Terminal: masked prompt. Otherwise (an agent's shell):
+// a native dialog, so the agent can start the command and the user only pastes.
+async function readSecret(args, prompt, itemName, envName) {
+    if (args.includes("--stdin"))
+        return core.readSecretFromInput({ prompt, stdin: true });
+    if (process.stdin.isTTY && !args.includes("--dialog"))
+        return core.readSecretFromInput({ prompt, stdin: false });
+    const value = await core.readSecretFromDialog({ itemName, envName });
+    if (value)
+        return value;
+    if (value === "")
+        throw new Error("Empty secret");
+    fail("No terminal and no dialog here (SSH or no display). Run the command in a terminal, or pipe the value with --stdin.", 2);
+}
+function checkNames(envName, itemName) {
+    if (isLoaderEnvName(envName))
+        fail(`${envName} changes what programs load or run; it cannot be wired to a secret`, 2);
+    const problem = itemNameProblem(itemName);
+    if (problem)
+        fail(`Vault item name ${problem}`, 2);
+}
 function shellQuote(value) { return `'${value.replaceAll("'", "'\\''")}'`; }
 function failureCode(error) {
     const text = error instanceof Error ? error.message : String(error);
@@ -154,14 +179,14 @@ async function inject(args) {
         process.stdout.write(rendered);
         return;
     }
-    try {
-        await readFile(output);
-        if (!args.includes("--force"))
-            fail(`Refusing to overwrite ${output}; use --force`, 5);
-    }
-    catch { }
-    await writeFile(output, rendered, { mode: 0o600 });
-    await chmod(output, 0o600);
+    // lstat, and a private temp file renamed over the target, so a planted
+    // symlink (even a dangling one) is replaced instead of followed.
+    const exists = await lstat(output).then(() => true, () => false);
+    if (exists && !args.includes("--force"))
+        fail(`Refusing to overwrite ${output}; use --force`, 5);
+    const tmp = join(dirname(resolve(output)), `.${basename(output)}.tmp.${randomBytes(6).toString("hex")}`);
+    await writeFile(tmp, rendered, { mode: 0o600, flag: "wx" });
+    await rename(tmp, output);
     console.error(`rendered ${refs.length} reference(s) into ${output} (mode 0600)`);
 }
 const SKIP_DIRS = new Set([".git", "node_modules", "dist", ".next", ".venv"]);
@@ -216,6 +241,128 @@ async function scan(paths) {
     if (leaks)
         process.exitCode = 1;
 }
+async function importCommand(args) {
+    requireKnownFlags(args, ["--from", "--out", "--prefix", "--only", "--skip"], ["--yes", "--replace", "--force"]);
+    const from = valueAfter(args, "--from") ?? ".env";
+    const yes = args.includes("--yes");
+    const replace = args.includes("--replace");
+    if (replace && (from === "-" || valueAfter(args, "--out")))
+        fail("--replace rewrites the --from file; it cannot be combined with stdin or --out", 2);
+    if (from === "-" && process.stdin.isTTY)
+        fail("--from - needs the .env piped on stdin", 2);
+    const baseDir = from === "-" ? process.cwd() : dirname(resolve(from));
+    const out = replace ? resolve(from) : resolve(valueAfter(args, "--out") ?? join(baseDir, ".env.refs"));
+    const prefix = valueAfter(args, "--prefix") ?? basename(baseDir);
+    if (!/^[A-Za-z0-9._-]+$/.test(prefix))
+        fail("--prefix may contain only letters, digits, '.', '_' and '-' (set it with --prefix)", 2);
+    const list = (flag) => (valueAfter(args, flag) ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+    const only = list("--only");
+    const skip = list("--skip");
+    let text;
+    try {
+        text = from === "-" ? await readStdin() : await readFile(from, "utf8");
+    }
+    catch {
+        fail(`Cannot read ${from}`, 2);
+    }
+    const { entries, errors } = parseDotenvStrict(text);
+    if (errors.length) {
+        for (const error of errors)
+            console.error(`${from}:${error.line} ${error.reason}`);
+        fail(`${errors.length} line(s) cannot be imported safely; fix them or move them out of the file`, 2);
+    }
+    for (const name of [...only, ...skip])
+        if (!entries.some((entry) => entry.name === name))
+            fail(`--only/--skip name not in ${from}: ${name}`, 2);
+    await core.ensureSession();
+    const existing = await core.findItems(prefix);
+    const rows = [];
+    for (const entry of entries) {
+        if (isRef(entry.value)) {
+            rows.push({ entry, kind: "ref" });
+            continue;
+        }
+        const secret = (only.length ? only.includes(entry.name) : looksSecret(entry.name, entry.value)) && !skip.includes(entry.name);
+        if (!secret) {
+            rows.push({ entry, kind: "literal" });
+            continue;
+        }
+        const item = `${prefix} ${entry.name}`;
+        const matches = existing.filter((candidate) => candidate.name.toLowerCase() === item.toLowerCase());
+        if (matches.length > 1) {
+            rows.push({ entry, item, kind: "conflict", note: "more than one vault item has this name" });
+            continue;
+        }
+        if (matches.length === 0) {
+            rows.push({ entry, item, kind: "new" });
+            continue;
+        }
+        const current = await core.resolveRef({ item: matches[0].id, field: "password" });
+        rows.push(current === entry.value
+            ? { entry, item, kind: "reuse", note: "same value already in the vault" }
+            : { entry, item, kind: "conflict", note: "vault item exists with a different value" });
+    }
+    const width = Math.max(4, ...rows.map((row) => row.entry.name.length));
+    console.log(`import plan for ${from} (item prefix "${prefix}")`);
+    for (const row of rows) {
+        const label = row.kind === "literal" ? "literal   kept" : row.kind === "ref" ? "reference kept"
+            : row.kind === "conflict" ? `secret    conflict: ${row.note} ("${row.item}")`
+                : `secret    ${row.kind.padEnd(8)} -> bw://${row.item}${row.note ? `  (${row.note})` : ""}`;
+        const short = row.item && row.entry.value.length < 6 ? "  [under 6 characters: stored, but too short to be masked]" : "";
+        console.log(`  ${row.entry.name.padEnd(width)}  ${label}${short}`);
+    }
+    const count = (kind) => rows.filter((row) => row.kind === kind).length;
+    const toStore = rows.filter((row) => row.kind === "new" || row.kind === "reuse");
+    console.log(`${toStore.length + count("conflict")} secret(s): ${count("new")} new, ${count("reuse")} already in the vault, ${count("conflict")} conflict(s); ${count("literal")} literal(s), ${count("ref")} reference(s)`);
+    if (count("conflict"))
+        fail("Resolve the conflicts (choose another --prefix, or rename the vault items) before importing", 5);
+    if (!toStore.length) {
+        console.log("Nothing to import.");
+        return;
+    }
+    const outExists = await stat(out).then(() => true, () => false);
+    if (outExists && !replace && !args.includes("--force"))
+        fail(`${out} already exists; use --force to overwrite it`, 5);
+    if (!yes) {
+        console.log(`Dry run: nothing written. Re-run with --yes to create ${count("new")} item(s) and write ${out}`);
+        return;
+    }
+    const created = [];
+    for (const row of rows) {
+        if (row.kind !== "new")
+            continue;
+        try {
+            await core.createSecretItem({ itemName: row.item, secret: row.entry.value, envName: row.entry.name, notes: `Imported by ${BRAND.bin} from ${basename(from === "-" ? "stdin" : from)}` });
+        }
+        catch {
+            if (created.length)
+                console.error(`Created before the failure: ${created.join(", ")}`);
+            fail(`Failed to create the vault item for ${row.entry.name}; nothing was written to ${out}`, 3);
+        }
+        created.push(row.entry.name);
+    }
+    for (const row of toStore) {
+        let value = null;
+        try {
+            value = await core.resolveRef({ item: row.item, field: "password" });
+        }
+        catch { }
+        if (value !== row.entry.value)
+            fail(`Verification failed for ${row.entry.name}: the vault does not return the imported value; nothing was written to ${out}`, 4);
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const lines = text.split(/\r?\n/);
+    for (const row of toStore)
+        lines[row.entry.line - 1] = `${row.entry.exported ? "export " : ""}${row.entry.name}=bw://${row.item}`;
+    const mode = replace ? (await stat(out)).mode & 0o777 : 0o600;
+    const tmp = `${out}.tmp.${randomBytes(6).toString("hex")}`;
+    await writeFile(tmp, lines.join(eol), { mode, flag: "wx" });
+    await rename(tmp, out);
+    await core.audit("import", toStore.map((row) => row.entry.name), "cli");
+    console.log(`imported ${toStore.length} secret(s) (${created.length} new); wrote ${out}`);
+    if (!replace && from !== "-")
+        console.log(`${from} still holds the plaintext values. Check with \`${BRAND.bin} run --env-file ${relative(process.cwd(), out) || out} -- <cmd>\`, then delete it or re-run with --replace.`);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args.shift();
@@ -320,17 +467,21 @@ async function main() {
             return;
         }
         if (command === "add") {
-            requireKnownFlags(args, ["--env", "--item", "--notes", "--target"], ["--stdin"]);
+            requireKnownFlags(args, ["--env", "--item", "--notes", "--target"], ["--stdin", "--dialog"]);
             const envName = valueAfter(args, "--env");
             const itemName = valueAfter(args, "--item");
             const notes = valueAfter(args, "--notes");
             if (!envName || !itemName || !ENV_NAME_RE.test(envName))
                 fail(usage, 2);
+            checkNames(envName, itemName);
             const reference = core.referenceFor(itemName);
             const targets = targetList(valueAfter(args, "--target"));
             await core.ensureSession();
-            const secret = await core.readSecretFromInput({ prompt: `Paste secret for ${envName}: `, stdin: args.includes("--stdin") });
+            if ((await core.findItems(itemName)).some((item) => item.name.toLowerCase() === itemName.toLowerCase()))
+                fail(`Vault item already exists: ${itemName}`, 5);
+            const secret = await readSecret(args, `Paste secret for ${envName}: `, itemName, envName);
             await core.createSecretItem({ itemName, secret, envName, notes });
+            await core.audit("add", [envName], "cli");
             let conflict = false;
             for (const path of targets) {
                 const result = await core.writeAuthEntry(path, envName, reference);
@@ -338,6 +489,7 @@ async function main() {
                     conflict = true;
             }
             const verified = (await core.resolveShellValue(reference)) !== null;
+            await core.refreshRedactIndex();
             console.log(`created item=${itemName} env=${envName} targets=${targets.join(",")} verified=${verified ? "yes" : "no"}`);
             if (conflict) {
                 console.error("Item created, but one or more auth targets already contained the environment name.");
@@ -345,14 +497,20 @@ async function main() {
             }
             return;
         }
+        if (command === "import") {
+            await importCommand(args);
+            return;
+        }
         if (command === "rotate") {
-            requireKnownFlags(args, ["--item"], ["--stdin"]);
+            requireKnownFlags(args, ["--item"], ["--stdin", "--dialog"]);
             const itemName = valueAfter(args, "--item");
             if (!itemName)
                 fail(usage, 2);
             await core.ensureSession();
-            const secret = await core.readSecretFromInput({ prompt: "Paste replacement secret: ", stdin: args.includes("--stdin") });
+            const secret = await readSecret(args, "Paste replacement secret: ", itemName);
             await core.rotateSecretItem({ itemName, secret });
+            await core.audit("rotate", [itemName], "cli");
+            await core.refreshRedactIndex();
             console.log(`rotated item=${itemName}`);
             return;
         }
@@ -362,6 +520,8 @@ async function main() {
             const itemName = valueAfter(args, "--item");
             if (!envName || !itemName || !ENV_NAME_RE.test(envName))
                 fail(usage, 2);
+            if (isLoaderEnvName(envName))
+                fail(`${envName} changes what programs load or run; it cannot be wired to a secret`, 2);
             const reference = core.referenceFor(itemName);
             const targets = targetList(valueAfter(args, "--target"));
             for (const path of targets) {

package/dist/core.d.ts

@@ -78,6 +78,7 @@ export declare function buildEnvMap(): Promise<Record<string, string>>;
 export declare function redactionValues(wired?: Record<string, string>): Promise<Record<string, string>>;
 export declare function indexValues(wired?: Record<string, string>): Record<string, string>;
 export declare function writeRedactIndex(values: Record<string, string>): Promise<RedactIndex>;
+export declare function refreshRedactIndex(): Promise<void>;
 export declare function readRedactIndex(): Promise<RedactIndex | null>;
 export declare function findItems(search: string): Promise<Array<{
     id: string;
@@ -103,3 +104,7 @@ export declare function readSecretFromInput(opts: {
     prompt: string;
     stdin: boolean;
 }): Promise<string>;
+export declare function readSecretFromDialog(opts: {
+    itemName: string;
+    envName?: string;
+}): Promise<string | null>;