@nightlybuildgroup/vault 1.2.0 → 1.4.0

package/README.md

@@ -32,6 +32,12 @@ nbg-pw get "GitHub" --field username   # a built-in field
 nbg-pw get "GitHub" --custom apiToken  # a custom field, looked up by name
 nbg-pw get "My Visa" --field number    # a credit-card field (see below)
 nbg-pw list "My Visa"               # show an item's field names + types, no values
+printf '%s' "$pw" | nbg-pw add "GitHub" --username octocat --password-stdin
+printf '%s' "$pw" | nbg-pw edit "GitHub" --password-stdin   # update an existing item
+nbg-pw attach "GitHub" --file ./key.pem   # add an attachment; --list/--get/--delete too
+nbg-pw delete "GitHub"              # soft-delete to trash (alias: rm; --permanent skips it)
+nbg-pw items --search git           # list item names; also: folders, collections
+nbg-pw generate --length 24 --symbols   # generate a password (no vault needed)
 nbg-pw serve --port 8087            # local bw REST API for fast repeated reads
 nbg-pw status                       # presence + auth state (no secrets)
 nbg-pw doctor                       # diagnose bw / Keychain / connectivity
@@ -39,6 +45,125 @@ nbg-pw logout                       # lock the session
 nbg-pw reset                        # log out and delete stored credentials
 ```
 
+### Adding items (`add`)
+
+Creates a **login** item. The password never goes on the command line (it would
+be visible in `ps`) — it's read from stdin, or supplied via `--json`.
+
+```sh
+# Flag mode — password piped on stdin:
+printf '%s' "$pw" | nbg-pw add "GitHub" \
+  --username octocat \
+  --url https://github.com \
+  --notes "work account" \
+  --folder "Agents" \
+  --field plan=pro \
+  --field-hidden token="$tok" \
+  --password-stdin
+```
+
+Options: `--username`, `--url` (repeatable), `--notes`, `--folder` (resolved by
+name, **created if missing**), `--collection` / `--organization` (shares the item
+into an org collection), `--field name=value` (text, repeatable),
+`--field-hidden name=value` (hidden, repeatable), `--totp`. On success it prints
+`Created "<name>" (<id>)` — never any secret value.
+
+> Note: in flag mode, `--field-hidden` values still pass through argv. For
+> secret custom fields use `--json` (below), which keeps **everything** off the
+> command line.
+
+#### JSON mode — secret-safe bulk automation
+
+`nbg-pw add --json` reads one entry as a JSON object on stdin, so every value
+(password, hidden fields, notes) stays off argv:
+
+```sh
+jq -n --arg name GitHub --arg u octocat --arg p "$pw" --arg t "$tok" \
+  '{name:$name, username:$u, password:$p, uris:["https://github.com"],
+    folder:"Agents", fields:[{name:"token", value:$t, type:1}]}' \
+  | nbg-pw add --json
+```
+
+Accepted keys: `name` (required), `username`, `password`, `uris` (array),
+`notes`, `totp`, `folder`, `collection`, `organization`, and `fields`
+(`[{name, value, type}]`; type `0` = text, `1` = hidden).
+
+#### Migrating a KeePass `.kdbx` to Bitwarden
+
+Loop your KeePass entries and pipe each into `add --json` — secrets flow through
+stdin only:
+
+```sh
+DB=~/Documents/Agents.kdbx
+for path in $(keepassxc-cli ls -R -f "$DB"); do
+  [ "${path%/}" != "$path" ] && continue   # skip groups
+  user=$(keepassxc-cli show -q -a UserName "$DB" "$path")
+  pass=$(keepassxc-cli show -q -a Password "$DB" "$path")
+  url=$( keepassxc-cli show -q -a URL      "$DB" "$path")
+  group=$(dirname "$path")
+  jq -n --arg n "$(basename "$path")" --arg u "$user" --arg p "$pass" \
+        --arg url "$url" --arg f "$group" \
+     '{name:$n, username:$u, password:$p,
+       uris:(if $url=="" then [] else [$url] end),
+       folder:(if $f=="." then null else $f end)}' \
+    | nbg-pw add --json
+done
+```
+
+### Editing items (`edit`)
+
+Fetch-merge-write: only the flags you pass are changed; everything else stays.
+Same secret discipline as `add` — the password comes from stdin.
+
+```sh
+printf '%s' "$newpw" | nbg-pw edit "GitHub" --password-stdin
+nbg-pw edit "GitHub" --notes "rotated 2026-06" --field plan=enterprise
+nbg-pw edit "GitHub" --folder "Agents"        # move into a folder (created if missing)
+```
+
+Flags mirror `add`: `--username`, `--url` (repeatable, **replaces** the URI list),
+`--notes`, `--totp`, `--field`/`--field-hidden` (upsert by name), `--folder`,
+`--password-stdin`.
+
+### Deleting (`delete` / `rm`)
+
+```sh
+nbg-pw delete "GitHub"               # soft-delete to trash
+nbg-pw delete "GitHub" --permanent   # skip the trash
+nbg-pw delete --folder "Agents"      # delete a folder
+```
+
+### Attachments (`attach`)
+
+```sh
+nbg-pw attach "GitHub" --file ./deploy-key.pem    # upload
+nbg-pw attach "GitHub" --list                      # id, filename, size (no contents)
+nbg-pw attach "GitHub" --get deploy-key.pem --output ./key.pem   # download
+nbg-pw attach "GitHub" --delete <attachment-id>    # remove
+```
+
+### Browsing the vault (`items`, `folders`, `collections`)
+
+Names only, never values — handy for scripting and for finding the exact item
+name to pass to `get`/`edit`/`attach`.
+
+```sh
+nbg-pw items                      # every item name
+nbg-pw items --search git         # filtered by search
+nbg-pw items --folder "Agents"    # filtered by folder
+nbg-pw folders                    # folder names
+nbg-pw collections                # collection names
+```
+
+### Generating secrets (`generate`)
+
+Pure generator — needs no vault session.
+
+```sh
+nbg-pw generate --length 24 --uppercase --number --symbols
+nbg-pw generate --passphrase --words 5 --separator - --capitalize
+```
+
 ### Credit-card items
 
 Credit cards have no username or password — just card data. `bw` has no native

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightlybuildgroup/vault",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Store Vaultwarden/Bitwarden credentials in the macOS Keychain and read secrets back for local agents.",
   "type": "module",
   "bin": {

package/src/bw.js

@@ -102,6 +102,130 @@ export async function getCardField({ item, field, session }, deps = {}) {
   return String(value);
 }
 
+// `bw create`/`bw move` read the object as base64 JSON. We pass it on stdin
+// (never argv), so secret values in the payload stay off the process list.
+function encode(obj) {
+  return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+
+export async function createItem({ item, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['create', 'item'], {
+    env: { BW_SESSION: session },
+    input: encode(item),
+  });
+  return JSON.parse(stdout);
+}
+
+export async function listFolders({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'folders'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+export async function createFolder({ name, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['create', 'folder'], {
+    env: { BW_SESSION: session },
+    input: encode({ name }),
+  });
+  return JSON.parse(stdout);
+}
+
+export async function listCollections({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'collections'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+export async function listOrganizations({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['list', 'organizations'], { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+// Share an existing item into an organization's collection(s). This is bw's only
+// path to put an item in a collection; the item must already exist.
+export async function moveItemToCollection({ itemId, organizationId, collectionIds, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  await run('bw', ['move', itemId, organizationId], {
+    env: { BW_SESSION: session },
+    input: encode(collectionIds),
+  });
+}
+
+export async function editItem({ id, item, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['edit', 'item', id], {
+    env: { BW_SESSION: session },
+    input: encode(item),
+  });
+  return JSON.parse(stdout);
+}
+
+export async function deleteItem({ id, permanent, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const args = ['delete', 'item', id];
+  if (permanent) args.push('--permanent');
+  await run('bw', args, { env: { BW_SESSION: session } });
+}
+
+export async function deleteFolder({ id, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  await run('bw', ['delete', 'folder', id], { env: { BW_SESSION: session } });
+}
+
+export async function deleteAttachment({ id, itemId, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  await run('bw', ['delete', 'attachment', id, '--itemid', itemId], { env: { BW_SESSION: session } });
+}
+
+export async function listItems({ search, folderId, collectionId, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const args = ['list', 'items'];
+  if (search) args.push('--search', search);
+  if (folderId) args.push('--folderid', folderId);
+  if (collectionId) args.push('--collectionid', collectionId);
+  const { stdout } = await run('bw', args, { env: { BW_SESSION: session } });
+  return JSON.parse(stdout);
+}
+
+// `bw generate` needs no vault session — it's a pure generator.
+export async function generate(opts = {}, deps = {}) {
+  const run = deps.run ?? realRun;
+  const args = ['generate'];
+  if (opts.passphrase) args.push('--passphrase');
+  if (opts.length != null) args.push('--length', String(opts.length));
+  if (opts.uppercase) args.push('--uppercase');
+  if (opts.lowercase) args.push('--lowercase');
+  if (opts.number) args.push('--number');
+  if (opts.special) args.push('--special');
+  if (opts.words != null) args.push('--words', String(opts.words));
+  if (opts.separator != null) args.push('--separator', opts.separator);
+  if (opts.capitalize) args.push('--capitalize');
+  const { stdout } = await run('bw', args);
+  return stdout;
+}
+
+export async function createAttachment({ itemId, file, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const { stdout } = await run('bw', ['create', 'attachment', '--file', file, '--itemid', itemId], {
+    env: { BW_SESSION: session },
+  });
+  return JSON.parse(stdout);
+}
+
+// Downloads to `output` (a file path) or, with `raw`, returns the content. bw
+// writes the file itself; we return whatever it prints (e.g. "Saved <path>").
+export async function getAttachment({ itemId, attachment, output, raw, session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  const args = ['get', 'attachment', attachment, '--itemid', itemId];
+  if (output) args.push('--output', output);
+  if (raw) args.push('--raw');
+  const { stdout } = await run('bw', args, { env: { BW_SESSION: session }, trim: false });
+  return stdout;
+}
+
 export async function status(deps = {}) {
   const run = deps.run ?? realRun;
   const { stdout } = await run('bw', ['status']);

package/src/cli.js

@@ -3,14 +3,22 @@ const HELP = `nbg-pw — Vaultwarden credential helper for macOS
 Usage: nbg-pw <command> [options]
 
 Commands:
-  setup     Interactive wizard: store your Vaultwarden credentials in the Keychain
-  get       Fetch a secret value (e.g. nbg-pw get "GitHub" --field password)
-  list      Show an item's field names + types, no values (nbg-pw list "My Visa")
-  serve     Start a local bw API daemon (unlocked) for fast repeated reads
-  status    Show config + auth state (no secret values)
-  doctor    Diagnose bw / Keychain / server connectivity (--fix resets a wedged bw session)
-  logout    Lock the session (bw logout)
-  reset     Log out and delete the stored Keychain item
+  setup       Interactive wizard: store your Vaultwarden credentials in the Keychain
+  get         Fetch a secret value (e.g. nbg-pw get "GitHub" --field password)
+  add         Create a login item (flags or --json on stdin; for kdbx → bw imports)
+  edit        Update fields on an existing item (nbg-pw edit "GitHub" --notes ...)
+  delete      Delete an item or folder (alias: rm; --permanent skips trash)
+  attach      Manage an item's attachments (--file/--list/--get/--delete)
+  list        Show an item's field names + types, no values (nbg-pw list "My Visa")
+  items       List item names (--search, --folder, --collection)
+  folders     List folder names
+  collections List collection names
+  generate    Generate a password or passphrase (bw generate)
+  serve       Start a local bw API daemon (unlocked) for fast repeated reads
+  status      Show config + auth state (no secret values)
+  doctor      Diagnose bw / Keychain / server connectivity (--fix resets a wedged bw session)
+  logout      Lock the session (bw logout)
+  reset       Log out and delete the stored Keychain item
 `;
 
 export async function runCli(argv, deps = {}) {
@@ -46,19 +54,37 @@ export async function runCli(argv, deps = {}) {
 }
 
 async function loadCommands() {
-  const [setup, get, list, status, doctor, serve, reset] = await Promise.all([
-    import('./commands/setup.js'),
-    import('./commands/get.js'),
-    import('./commands/list.js'),
-    import('./commands/status.js'),
-    import('./commands/doctor.js'),
-    import('./commands/serve.js'),
-    import('./commands/reset.js'),
-  ]);
+  const [setup, get, add, edit, del, attach, list, items, folders, collections, generate, status, doctor, serve, reset] =
+    await Promise.all([
+      import('./commands/setup.js'),
+      import('./commands/get.js'),
+      import('./commands/add.js'),
+      import('./commands/edit.js'),
+      import('./commands/delete.js'),
+      import('./commands/attach.js'),
+      import('./commands/list.js'),
+      import('./commands/items.js'),
+      import('./commands/folders.js'),
+      import('./commands/collections.js'),
+      import('./commands/generate.js'),
+      import('./commands/status.js'),
+      import('./commands/doctor.js'),
+      import('./commands/serve.js'),
+      import('./commands/reset.js'),
+    ]);
   return {
     setup: setup.default,
     get: get.default,
+    add: add.default,
+    edit: edit.default,
+    delete: del.default,
+    rm: del.default,
+    attach: attach.default,
     list: list.default,
+    items: items.default,
+    folders: folders.default,
+    collections: collections.default,
+    generate: generate.default,
     status: status.default,
     doctor: doctor.default,
     serve: serve.default,

package/src/commands/add.js

@@ -0,0 +1,163 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const USAGE =
+  'usage: nbg-pw add <name> [--username <u>] [--url <uri>]... [--notes <n>] ' +
+  '[--folder <name>] [--collection <name>] [--organization <name|id>] ' +
+  '[--field <name>=<value>]... [--field-hidden <name>=<value>]... [--totp <secret>] ' +
+  '[--password-stdin]\n   or: nbg-pw add --json   (reads one entry as a JSON object on stdin)';
+
+// `--field name=value` → { name, value, type }. Splits on the FIRST `=` so the
+// value may itself contain `=`.
+function parseField(raw, type) {
+  const eq = raw.indexOf('=');
+  if (eq === -1) throw new Error(`--field expects name=value, got "${raw}"`);
+  return { name: raw.slice(0, eq), value: raw.slice(eq + 1), type };
+}
+
+export function parseAddArgs(args) {
+  const opts = { uris: [], fields: [], passwordStdin: false, json: false };
+  let name = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const need = () => {
+      const v = args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case '--json': opts.json = true; break;
+      case '--password-stdin': opts.passwordStdin = true; break;
+      case '--username': opts.username = need(); break;
+      case '--url': opts.uris.push(need()); break;
+      case '--notes': opts.notes = need(); break;
+      case '--folder': opts.folder = need(); break;
+      case '--collection': opts.collection = need(); break;
+      case '--organization': opts.organization = need(); break;
+      case '--totp': opts.totp = need(); break;
+      case '--field': opts.fields.push(parseField(need(), 0)); break;
+      case '--field-hidden': opts.fields.push(parseField(need(), 1)); break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option "${a}"\n${USAGE}`);
+        if (name === null) name = a;
+        else throw new Error(`unexpected argument "${a}"\n${USAGE}`);
+    }
+  }
+  if (!opts.json && name === null) throw new Error(USAGE);
+  opts.name = name;
+  return opts;
+}
+
+// Turns a normalized entry into the Bitwarden login-item JSON shape.
+export function buildLoginItem(entry) {
+  const item = {
+    type: 1,
+    name: entry.name,
+    notes: entry.notes ?? null,
+    login: {
+      username: entry.username ?? null,
+      password: entry.password ?? null,
+      uris: (entry.uris ?? []).filter(Boolean).map((uri) => ({ match: null, uri })),
+      totp: entry.totp ?? null,
+    },
+    fields: (entry.fields ?? []).map((f) => ({ name: f.name, value: f.value ?? '', type: f.type ?? 0 })),
+  };
+  if (entry.folderId) item.folderId = entry.folderId;
+  return item;
+}
+
+async function resolveFolderId(bw, session, folderName) {
+  const folders = await bw.listFolders({ session });
+  const found = folders.find((f) => f.name === folderName && f.id);
+  if (found) return found.id;
+  const created = await bw.createFolder({ name: folderName, session });
+  return created.id;
+}
+
+async function resolveCollection(bw, session, collectionName, org) {
+  const collections = await bw.listCollections({ session });
+  let matches = collections.filter((c) => c.name === collectionName);
+  if (org) {
+    const orgs = await bw.listOrganizations({ session });
+    const match = orgs.find((o) => o.id === org || o.name === org);
+    const orgId = match ? match.id : org;
+    matches = matches.filter((c) => c.organizationId === orgId);
+  }
+  if (matches.length === 0) {
+    throw new Error(`no collection named "${collectionName}"${org ? ` in organization "${org}"` : ''}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`multiple collections named "${collectionName}"; disambiguate with --organization <name|id>`);
+  }
+  return matches[0];
+}
+
+export async function runAdd(args, deps) {
+  const { keychain, bw, out, err, readStdin } = deps;
+  const opts = parseAddArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  let entry;
+  if (opts.json) {
+    const parsed = JSON.parse(await readStdin());
+    if (!parsed.name) throw new Error('json entry requires a "name"');
+    entry = parsed;
+  } else {
+    entry = {
+      name: opts.name,
+      username: opts.username,
+      uris: opts.uris,
+      notes: opts.notes,
+      totp: opts.totp,
+      fields: opts.fields,
+      folder: opts.folder,
+      collection: opts.collection,
+      organization: opts.organization,
+    };
+    if (opts.passwordStdin) entry.password = (await readStdin()).replace(/\r?\n$/, '');
+  }
+
+  const session = await bw.ensureSession(config);
+
+  if (entry.folder) entry.folderId = await resolveFolderId(bw, session, entry.folder);
+
+  const created = await bw.createItem({ item: buildLoginItem(entry), session });
+
+  if (entry.collection) {
+    const col = await resolveCollection(bw, session, entry.collection, entry.organization);
+    await bw.moveItemToCollection({
+      itemId: created.id,
+      organizationId: col.organizationId,
+      collectionIds: [col.id],
+      session,
+    });
+  }
+
+  out(`Created "${created.name}" (${created.id})\n`);
+  return 0;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export default async function add(args) {
+  return runAdd(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    readStdin,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/attach.js

@@ -0,0 +1,92 @@
+import path from 'node:path';
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const USAGE =
+  'usage: nbg-pw attach <item> [--file <path> | --list | --get <id|name> [--output <path>] [--raw] | --delete <id>]';
+
+export function parseAttachArgs(args) {
+  let item = null;
+  let file = null;
+  let list = false;
+  let get = null;
+  let output = null;
+  let raw = false;
+  let del = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const need = () => {
+      const v = args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case '--file': file = need(); break;
+      case '--list': list = true; break;
+      case '--get': get = need(); break;
+      case '--output': output = need(); break;
+      case '--raw': raw = true; break;
+      case '--delete': del = need(); break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option "${a}"\n${USAGE}`);
+        if (item === null) item = a;
+    }
+  }
+  if (!item) throw new Error(USAGE);
+  const actions = [file !== null, get !== null, del !== null].filter(Boolean).length;
+  if (actions > 1) throw new Error('choose one of --file, --get, or --delete');
+  return { item, file, list, get, output, raw, delete: del };
+}
+
+export async function runAttach(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  const { item, file, get, output, raw, delete: del } = parseAttachArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+  const resolved = await bw.getItemJson({ item, session });
+  const itemId = resolved.id;
+
+  if (file !== null) {
+    await bw.createAttachment({ itemId, file, session });
+    out(`Attached "${path.basename(file)}" to "${item}"\n`);
+    return 0;
+  }
+
+  if (get !== null) {
+    const result = await bw.getAttachment({ itemId, attachment: get, output, raw, session });
+    out(result.endsWith('\n') ? result : result + '\n');
+    return 0;
+  }
+
+  if (del !== null) {
+    await bw.deleteAttachment({ id: del, itemId, session });
+    out(`Deleted attachment ${del} from "${item}"\n`);
+    return 0;
+  }
+
+  // Default action: list the item's attachments.
+  const attachments = resolved.attachments ?? [];
+  if (attachments.length === 0) {
+    out('(no attachments)\n');
+    return 0;
+  }
+  for (const a of attachments) {
+    out(`${a.id}  ${a.fileName} (${a.sizeName ?? a.size})\n`);
+  }
+  return 0;
+}
+
+export default async function attach(args) {
+  return runAttach(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/collections.js

@@ -0,0 +1,35 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+export function parseCollectionsArgs(args) {
+  if (args.length > 0) throw new Error(`unexpected argument: ${args[0]}`);
+  return {};
+}
+
+export async function runCollections(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  parseCollectionsArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+  const collections = await bw.listCollections({ session });
+  const names = collections
+    .map((c) => c.name)
+    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  for (const name of names) out(name + '\n');
+  return 0;
+}
+
+export default async function collections(args) {
+  return runCollections(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/delete.js

@@ -0,0 +1,69 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const USAGE = 'usage: nbg-pw delete <item> [--permanent]\n   or: nbg-pw delete --folder <name>';
+
+export function parseDeleteArgs(args) {
+  let item = null;
+  let folder = null;
+  let permanent = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const need = () => {
+      const v = args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case '--permanent': permanent = true; break;
+      case '--folder': folder = need(); break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option "${a}"\n${USAGE}`);
+        if (item === null) item = a;
+        else throw new Error(`unexpected argument "${a}"\n${USAGE}`);
+    }
+  }
+  if (item !== null && folder !== null) {
+    throw new Error(`pass either <item> or --folder, not both\n${USAGE}`);
+  }
+  if (item === null && folder === null) {
+    throw new Error(USAGE);
+  }
+  return { item, folder, permanent };
+}
+
+export async function runDelete(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  const opts = parseDeleteArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+
+  if (opts.folder !== null) {
+    const folders = await bw.listFolders({ session });
+    const found = folders.find((f) => f.name === opts.folder && f.id);
+    if (!found) throw new Error(`no folder named "${opts.folder}"`);
+    await bw.deleteFolder({ id: found.id, session });
+    out(`Deleted folder "${opts.folder}"\n`);
+    return 0;
+  }
+
+  const resolved = await bw.getItemJson({ item: opts.item, session });
+  await bw.deleteItem({ id: resolved.id, permanent: opts.permanent, session });
+  out(`Deleted "${opts.item}"\n`);
+  return 0;
+}
+
+export default async function del(args) {
+  return runDelete(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/edit.js

@@ -0,0 +1,111 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+const USAGE =
+  'usage: nbg-pw edit <item> [--username <u>] [--password-stdin] [--url <uri>]... ' +
+  '[--notes <n>] [--totp <secret>] [--field <name>=<value>]... ' +
+  '[--field-hidden <name>=<value>]... [--folder <name>]';
+
+// `--field name=value` → { name, value, type }. Splits on the FIRST `=` so the
+// value may itself contain `=`.
+function parseField(raw, type) {
+  const eq = raw.indexOf('=');
+  if (eq === -1) throw new Error(`--field expects name=value, got "${raw}"`);
+  return { name: raw.slice(0, eq), value: raw.slice(eq + 1), type };
+}
+
+export function parseEditArgs(args) {
+  const opts = { uris: [], fields: [], passwordStdin: false };
+  let item = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    const need = () => {
+      const v = args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      return v;
+    };
+    switch (a) {
+      case '--password-stdin': opts.passwordStdin = true; break;
+      case '--username': opts.username = need(); break;
+      case '--url': opts.uris.push(need()); break;
+      case '--notes': opts.notes = need(); break;
+      case '--totp': opts.totp = need(); break;
+      case '--field': opts.fields.push(parseField(need(), 0)); break;
+      case '--field-hidden': opts.fields.push(parseField(need(), 1)); break;
+      case '--folder': opts.folder = need(); break;
+      default:
+        if (a.startsWith('--')) throw new Error(`unknown option "${a}"\n${USAGE}`);
+        if (item === null) item = a;
+        else throw new Error(`unexpected argument "${a}"\n${USAGE}`);
+    }
+  }
+  if (item === null) throw new Error(USAGE);
+  opts.item = item;
+  return opts;
+}
+
+// Upsert a custom field by name onto item.fields: update in place if present,
+// otherwise append.
+function upsertField(item, { name, value, type }) {
+  const existing = item.fields.find((f) => f.name === name);
+  if (existing) existing.value = value;
+  else item.fields.push({ name, value, type });
+}
+
+async function resolveFolderId(bw, session, folderName) {
+  const folders = await bw.listFolders({ session });
+  const found = folders.find((f) => f.name === folderName && f.id);
+  if (found) return found.id;
+  const created = await bw.createFolder({ name: folderName, session });
+  return created.id;
+}
+
+export async function runEdit(args, deps) {
+  const { keychain, bw, out, err, readStdin } = deps;
+  const opts = parseEditArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+
+  const item = await bw.getItemJson({ item: opts.item, session });
+  item.login ??= {};
+  item.fields ??= [];
+
+  if (opts.username !== undefined) item.login.username = opts.username;
+  if (opts.passwordStdin) item.login.password = (await readStdin()).replace(/\r?\n$/, '');
+  if (opts.uris.length > 0) item.login.uris = opts.uris.map((uri) => ({ match: null, uri }));
+  if (opts.notes !== undefined) item.notes = opts.notes;
+  if (opts.totp !== undefined) item.login.totp = opts.totp;
+  for (const field of opts.fields) upsertField(item, field);
+  if (opts.folder !== undefined) item.folderId = await resolveFolderId(bw, session, opts.folder);
+
+  const updated = await bw.editItem({ id: item.id, item, session });
+
+  out(`Updated "${updated.name}" (${updated.id})\n`);
+  return 0;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+export default async function edit(args) {
+  return runEdit(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    readStdin,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/folders.js

@@ -0,0 +1,35 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+export function parseFoldersArgs(args) {
+  if (args.length > 0) throw new Error(`unexpected argument: ${args[0]}`);
+  return {};
+}
+
+export async function runFolders(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  parseFoldersArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+  const folders = await bw.listFolders({ session });
+  const names = folders
+    .map((f) => f.name)
+    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  for (const name of names) out(name + '\n');
+  return 0;
+}
+
+export default async function folders(args) {
+  return runFolders(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/commands/generate.js

@@ -0,0 +1,51 @@
+import * as bwModule from '../bw.js';
+
+export function parseGenerateArgs(args) {
+  const opts = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--length') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--length requires a value');
+      const n = Number(v);
+      if (Number.isNaN(n)) throw new Error('--length must be a number');
+      opts.length = n;
+    }
+    else if (arg === '--uppercase' || arg === '-u') { opts.uppercase = true; }
+    else if (arg === '--lowercase') { opts.lowercase = true; }
+    else if (arg === '--number' || arg === '-n') { opts.number = true; }
+    else if (arg === '--symbols' || arg === '--special' || arg === '-s') { opts.special = true; }
+    else if (arg === '--passphrase' || arg === '-p') { opts.passphrase = true; }
+    else if (arg === '--words') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--words requires a value');
+      const n = Number(v);
+      if (Number.isNaN(n)) throw new Error('--words must be a number');
+      opts.words = n;
+    }
+    else if (arg === '--separator') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--separator requires a value');
+      opts.separator = v;
+    }
+    else if (arg === '--capitalize' || arg === '-c') { opts.capitalize = true; }
+    else if (arg.startsWith('-')) { throw new Error(`unknown option "${arg}"`); }
+    else { throw new Error(`unexpected argument "${arg}"`); }
+  }
+  return opts;
+}
+
+export async function runGenerate(args, deps) {
+  const { bw, out } = deps;
+  const opts = parseGenerateArgs(args);
+  const value = await bw.generate(opts);
+  out(value + '\n');
+  return 0;
+}
+
+export default async function generate(args) {
+  return runGenerate(args, {
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+  });
+}

package/src/commands/items.js

@@ -0,0 +1,76 @@
+import * as bwModule from '../bw.js';
+import * as keychainModule from '../keychain.js';
+
+export function parseItemsArgs(args) {
+  let search = null;
+  let folder = null;
+  let collection = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--search') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--search requires a value');
+      search = v;
+    } else if (args[i] === '--folder') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--folder requires a value');
+      folder = v;
+    } else if (args[i] === '--collection') {
+      const v = args[++i];
+      if (v === undefined) throw new Error('--collection requires a value');
+      collection = v;
+    } else {
+      throw new Error(`unknown option: ${args[i]}`);
+    }
+  }
+  return { search, folder, collection };
+}
+
+export async function runItems(args, deps) {
+  const { keychain, bw, out, err } = deps;
+  const { search, folder, collection } = parseItemsArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  const session = await bw.ensureSession(config);
+
+  let folderId;
+  if (folder !== null) {
+    const folders = await bw.listFolders({ session });
+    const match = folders.find((f) => f.name === folder && f.id);
+    if (!match) throw new Error(`no folder named "${folder}"`);
+    folderId = match.id;
+  }
+
+  let collectionId;
+  if (collection !== null) {
+    const collections = await bw.listCollections({ session });
+    const match = collections.find((c) => c.name === collection);
+    if (!match) throw new Error(`no collection named "${collection}"`);
+    collectionId = match.id;
+  }
+
+  const filters = { session };
+  if (search !== null) filters.search = search;
+  if (folderId !== undefined) filters.folderId = folderId;
+  if (collectionId !== undefined) filters.collectionId = collectionId;
+
+  const items = await bw.listItems(filters);
+  const names = items
+    .map((i) => i.name)
+    .sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+  for (const name of names) out(name + '\n');
+  return 0;
+}
+
+export default async function items(args) {
+  return runItems(args, {
+    keychain: keychainModule,
+    bw: bwModule,
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  });
+}

package/src/exec.js

@@ -5,6 +5,12 @@ export function run(cmd, args, opts = {}) {
   const doTrim = opts.trim !== false;
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { env });
+    // `opts.input` is written to the child's stdin (used to pass base64-encoded
+    // JSON to `bw create`/`bw move` without exposing secrets on the command line).
+    if (opts.input != null) {
+      child.stdin.on('error', () => {}); // ignore EPIPE if the child closes stdin early
+      child.stdin.end(opts.input);
+    }
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (d) => { stdout += d; });