@nightlybuildgroup/vault 1.3.0 → 1.5.0

package/README.md

@@ -33,6 +33,12 @@ 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 config set collection "Shared"   # new items share into this org collection
 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
@@ -105,6 +111,87 @@ for path in $(keepassxc-cli ls -R -f "$DB"); do
 done
 ```
 
+### Sharing new items with an organization (`config`)
+
+By default `add` creates items in the API account's **personal** vault, which
+other org members (and your own interactive login) can't see. To make every new
+item land in a shared **organization collection** instead, set a default — it's
+stored in your Keychain, never in this repo, so nothing org-specific is baked
+into the tool:
+
+```sh
+nbg-pw config set organization "Acme Inc"     # by name or id
+nbg-pw config set collection   "Shared"        # by name or id
+nbg-pw config show                             # current defaults
+nbg-pw config unset collection                 # back to personal-vault default
+```
+
+Once a default collection is set, every `add` shares the new item into it:
+
+```sh
+printf '%s' "$pw" | nbg-pw add "GitHub" --username octocat --password-stdin
+# → Created "GitHub" (…) → shared to "Shared"
+
+nbg-pw add "Personal Note" --personal          # opt a single item out (personal vault)
+```
+
+An explicit `--collection`/`--organization` on `add` overrides the default for
+that call. `status` shows the active default share.
+
+### 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.3.0",
+  "version": "1.5.0",
   "description": "Store Vaultwarden/Bitwarden credentials in the macOS Keychain and read secrets back for local agents.",
   "type": "module",
   "bin": {

package/src/bw.js

@@ -144,14 +144,101 @@ export async function listOrganizations({ session }, deps = {}) {
   return JSON.parse(stdout);
 }
 
+export async function sync({ session }, deps = {}) {
+  const run = deps.run ?? realRun;
+  await run('bw', ['sync'], { env: { BW_SESSION: session } });
+}
+
 // 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.
+// path to put an item in a collection; the item must already exist. bw's local
+// cache can lag a just-created item ("client copy ... out of date"); a sync +
+// single retry clears that.
 export async function moveItemToCollection({ itemId, organizationId, collectionIds, session }, deps = {}) {
   const run = deps.run ?? realRun;
-  await run('bw', ['move', itemId, organizationId], {
+  const move = () =>
+    run('bw', ['move', itemId, organizationId], { env: { BW_SESSION: session }, input: encode(collectionIds) });
+  try {
+    await move();
+  } catch (e) {
+    if (/out of date/i.test(e.message || '')) {
+      await run('bw', ['sync'], { env: { BW_SESSION: session } });
+      await move();
+    } else {
+      throw e;
+    }
+  }
+}
+
+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 },
-    input: encode(collectionIds),
   });
+  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 = {}) {

package/src/cli.js

@@ -3,15 +3,23 @@ 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)
-  add       Create a login item (flags or --json on stdin; for kdbx → bw imports)
-  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)
+  config      Show/set defaults, e.g. the org collection new items share into
+  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 = {}) {
@@ -47,21 +55,39 @@ export async function runCli(argv, deps = {}) {
 }
 
 async function loadCommands() {
-  const [setup, get, add, list, status, doctor, serve, reset] = await Promise.all([
-    import('./commands/setup.js'),
-    import('./commands/get.js'),
-    import('./commands/add.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, config, 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/config.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,
+    config: config.default,
     status: status.default,
     doctor: doctor.default,
     serve: serve.default,

package/src/commands/add.js

@@ -5,7 +5,7 @@ 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)';
+  '[--password-stdin] [--personal]\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 `=`.
@@ -16,7 +16,7 @@ function parseField(raw, type) {
 }
 
 export function parseAddArgs(args) {
-  const opts = { uris: [], fields: [], passwordStdin: false, json: false };
+  const opts = { uris: [], fields: [], passwordStdin: false, json: false, personal: false };
   let name = null;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -27,6 +27,7 @@ export function parseAddArgs(args) {
     };
     switch (a) {
       case '--json': opts.json = true; break;
+      case '--personal': opts.personal = true; break;
       case '--password-stdin': opts.passwordStdin = true; break;
       case '--username': opts.username = need(); break;
       case '--url': opts.uris.push(need()); break;
@@ -122,23 +123,36 @@ export async function runAdd(args, deps) {
     if (opts.passwordStdin) entry.password = (await readStdin()).replace(/\r?\n$/, '');
   }
 
+  // Where the item lands: an explicit --collection wins; otherwise the
+  // configured default shares every new item into the org collection, unless
+  // --personal (or a json `personal:true`) opts out into the personal vault.
+  const personal = opts.personal || entry.personal;
+  let collectionName = entry.collection;
+  let organizationName = entry.organization;
+  if (!personal && !collectionName && config.defaultCollection) {
+    collectionName = config.defaultCollection;
+    organizationName = organizationName ?? config.defaultOrganization;
+  }
+
   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);
+  let shared = '';
+  if (collectionName) {
+    const col = await resolveCollection(bw, session, collectionName, organizationName);
     await bw.moveItemToCollection({
       itemId: created.id,
       organizationId: col.organizationId,
       collectionIds: [col.id],
       session,
     });
+    shared = ` → shared to "${col.name}"`;
   }
 
-  out(`Created "${created.name}" (${created.id})\n`);
+  out(`Created "${created.name}" (${created.id})${shared}\n`);
   return 0;
 }
 

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/config.js

@@ -0,0 +1,60 @@
+import * as keychainModule from '../keychain.js';
+
+// User-facing key → stored config field.
+const KEYS = { organization: 'defaultOrganization', collection: 'defaultCollection' };
+
+const USAGE = 'usage: nbg-pw config [show | set <organization|collection> <value> | unset <organization|collection>]';
+
+export function parseConfigArgs(args) {
+  const [sub, ...rest] = args;
+  if (!sub || sub === 'show') return { action: 'show' };
+  if (sub === 'set') {
+    const [key, value] = rest;
+    if (!key || !(key in KEYS)) throw new Error(USAGE);
+    if (value === undefined) throw new Error('config set requires a value');
+    return { action: 'set', key, value };
+  }
+  if (sub === 'unset') {
+    const [key] = rest;
+    if (!key || !(key in KEYS)) throw new Error(USAGE);
+    return { action: 'unset', key };
+  }
+  throw new Error(`unknown config subcommand "${sub}"\n${USAGE}`);
+}
+
+export async function runConfig(args, deps) {
+  const { keychain, out, err } = deps;
+  const opts = parseConfigArgs(args);
+
+  const config = await keychain.readConfig();
+  if (!config) {
+    err('No stored credentials. Run "nbg-pw setup" first.\n');
+    return 1;
+  }
+
+  if (opts.action === 'show') {
+    out(`default organization: ${config.defaultOrganization ?? '(not set)'}\n`);
+    out(`default collection:   ${config.defaultCollection ?? '(not set)'}\n`);
+    return 0;
+  }
+
+  const field = KEYS[opts.key];
+  if (opts.action === 'set') {
+    config[field] = opts.value;
+    await keychain.writeConfig(config);
+    out(`Set default ${opts.key} = ${opts.value}\n`);
+  } else {
+    delete config[field];
+    await keychain.writeConfig(config);
+    out(`Unset default ${opts.key}\n`);
+  }
+  return 0;
+}
+
+export default async function config(args) {
+  return runConfig(args, {
+    keychain: keychainModule,
+    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/commands/status.js

@@ -12,6 +12,10 @@ export async function runStatus(args, deps) {
     out(`  stored creds:  yes\n`);
     out(`  server URL:    ${config.serverUrl}\n`);
     out(`  email:         ${config.email}\n`);
+    if (config.defaultCollection) {
+      const org = config.defaultOrganization ? `${config.defaultOrganization} / ` : '';
+      out(`  default share: ${org}${config.defaultCollection}\n`);
+    }
   } else {
     out('  stored creds:  No credentials stored (run "nbg-pw setup")\n');
   }

package/src/config.js

@@ -2,6 +2,8 @@ export const SERVICE = 'com.nightlybuild.vault';
 export const ACCOUNT = 'default';
 export const FIELDS = ['serverUrl', 'email', 'clientId', 'clientSecret', 'masterPassword'];
 export const READ_FIELDS = [...FIELDS, 'savedAt'];
+// Optional: when set, `add` shares new items into this org collection by default.
+export const OPTIONAL_FIELDS = ['defaultOrganization', 'defaultCollection'];
 
 export function isValidUrl(s) {
   if (typeof s !== 'string' || s.length === 0) return false;
@@ -26,6 +28,11 @@ export function validateConfig(obj) {
   }
   if (!isValidUrl(obj.serverUrl)) throw new Error('config serverUrl is not a valid URL');
   if (!isValidEmail(obj.email)) throw new Error('config email is not a valid email');
+  for (const f of OPTIONAL_FIELDS) {
+    if (obj[f] !== undefined && (typeof obj[f] !== 'string' || obj[f].length === 0)) {
+      throw new Error(`config field ${f} must be a non-empty string when set`);
+    }
+  }
   return obj;
 }