bwx 0.1.0 → 0.2.1

package/README.md

@@ -14,8 +14,11 @@ The native `bw` CLI requires interactive prompts and manual session management.
 ## Install
 
 ```bash
-bun install  # or npm install
-bun link     # makes `bwx` available globally
+# Global install
+bun install -g bwx
+
+# Or run without installing
+bunx bwx doctor
 ```
 
 Requires [Bitwarden CLI](https://bitwarden.com/help/cli/) (`bw`) installed and on PATH.
@@ -28,6 +31,9 @@ bwx config email your@email.com
 
 # Store master password in macOS Keychain
 bwx config master-password
+
+# Verify everything is ready
+bwx doctor
 ```
 
 ## Commands
@@ -40,6 +46,7 @@ bwx config master-password
 | `bwx unlock` | Unlock vault & cache session |
 | `bwx lock` | Lock vault & clear session |
 | `bwx sync` | Sync vault from server |
+| `bwx doctor` | Check setup (bw CLI, email, password, config) |
 
 ### Read
 

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "bwx",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
+  "keywords": [
+    "bitwarden",
+    "cli",
+    "vault",
+    "secrets",
+    "ai-agents",
+    "bun"
+  ],
   "files": [
     "bin",
     "src"

package/src/bw/types.ts

@@ -32,9 +32,13 @@ export const BW_TYPE_LABELS: Record<number, string> = {
 
 export const BW_TYPE_FROM_NAME: Record<string, BwItemType> = {
 	login: BwItemType.Login,
+	logins: BwItemType.Login,
 	note: BwItemType.SecureNote,
+	notes: BwItemType.SecureNote,
 	card: BwItemType.Card,
+	cards: BwItemType.Card,
 	identity: BwItemType.Identity,
+	identities: BwItemType.Identity,
 };
 
 // --- Field types ---

package/src/cli/commands/config.ts

@@ -6,7 +6,7 @@ import { loadConfig, saveConfig } from "../../config/store.ts";
 
 export function registerConfig(program: Command): void {
 	const configCmd = program
-		.command("config")
+		.command("config").alias("cfg")
 		.description("Manage bwx configuration");
 
 	configCmd

package/src/cli/commands/create.ts

@@ -13,7 +13,7 @@ function collect(val: string, prev: string[]): string[] {
 
 export function registerCreate(program: Command): void {
 	program
-		.command("create")
+		.command("create").alias("add")
 		.description("Create a new vault item")
 		.option("--type <type>", "Item type: login|note", "note")
 		.option("--name <name>", "Item name")

package/src/cli/commands/delete.ts

@@ -8,7 +8,7 @@ import pc from "picocolors";
 
 export function registerDelete(program: Command): void {
 	program
-		.command("delete")
+		.command("delete").alias("rm")
 		.description("Delete a vault item")
 		.argument("<item>", "Item name or ID")
 		.option("--permanent", "Permanently delete (no trash)")

package/src/cli/commands/doctor.ts

@@ -0,0 +1,157 @@
+import type { Command } from "commander";
+import { getGlobalOpts } from "../program.ts";
+import { emitData } from "../io.ts";
+import { loadConfig } from "../../config/store.ts";
+import pc from "picocolors";
+
+interface Check {
+	name: string;
+	ok: boolean;
+	detail?: string;
+	fix?: string;
+}
+
+export function registerDoctor(program: Command): void {
+	program
+		.command("doctor").alias("check")
+		.description("Check if bwx is ready to use")
+		.action(async function (this: Command) {
+			const opts = getGlobalOpts(this);
+			const checks: Check[] = [];
+
+			// 1. bw CLI installed
+			checks.push(await checkBwInstalled());
+
+			// 2. bw CLI version
+			if (checks[0]!.ok) {
+				checks.push(await checkBwVersion());
+			}
+
+			// 3. Email configured
+			checks.push(await checkEmail());
+
+			// 4. Master password in Keychain
+			checks.push(await checkMasterPassword());
+
+			// 5. Config dir writable
+			checks.push(await checkConfigDir());
+
+			if (opts.json || opts.plain) {
+				emitData(checks, opts);
+				return;
+			}
+
+			for (const check of checks) {
+				const icon = check.ok ? pc.green("✓") : pc.red("✗");
+				const name = check.ok ? check.name : pc.red(check.name);
+				let line = `${icon} ${name}`;
+				if (check.detail) {
+					line += pc.dim(` (${check.detail})`);
+				}
+				process.stderr.write(line + "\n");
+				if (!check.ok && check.fix) {
+					process.stderr.write(pc.dim(`  → ${check.fix}`) + "\n");
+				}
+			}
+
+			const failed = checks.filter((c) => !c.ok).length;
+			if (failed > 0) {
+				process.stderr.write(
+					"\n" + pc.red(`${failed} issue${failed > 1 ? "s" : ""} found`) + "\n",
+				);
+				process.exit(1);
+			} else {
+				process.stderr.write("\n" + pc.green("All good") + "\n");
+			}
+		});
+}
+
+async function checkBwInstalled(): Promise<Check> {
+	try {
+		const proc = Bun.spawn(["which", "bw"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const path = (await new Response(proc.stdout).text()).trim();
+		const code = await proc.exited;
+		if (code === 0 && path) {
+			return { name: "Bitwarden CLI", ok: true, detail: path };
+		}
+	} catch {}
+	return {
+		name: "Bitwarden CLI",
+		ok: false,
+		fix: "brew install bitwarden-cli",
+	};
+}
+
+async function checkBwVersion(): Promise<Check> {
+	try {
+		const proc = Bun.spawn(["bw", "--version"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		const version = (await new Response(proc.stdout).text()).trim();
+		const code = await proc.exited;
+		if (code === 0 && version) {
+			return { name: "bw version", ok: true, detail: version };
+		}
+	} catch {}
+	return { name: "bw version", ok: false, fix: "brew upgrade bitwarden-cli" };
+}
+
+async function checkEmail(): Promise<Check> {
+	const config = await loadConfig();
+	if (config.email) {
+		return { name: "Account email", ok: true, detail: config.email };
+	}
+	return {
+		name: "Account email",
+		ok: false,
+		fix: "bwx config email your@email.com",
+	};
+}
+
+async function checkMasterPassword(): Promise<Check> {
+	try {
+		const proc = Bun.spawn(
+			[
+				"security",
+				"find-generic-password",
+				"-a",
+				"bitwarden",
+				"-s",
+				"bitwarden-master",
+				"-w",
+			],
+			{ stdout: "pipe", stderr: "pipe" },
+		);
+		const pw = (await new Response(proc.stdout).text()).trim();
+		const code = await proc.exited;
+		if (code === 0 && pw) {
+			return { name: "Master password", ok: true, detail: "in Keychain" };
+		}
+	} catch {}
+	return {
+		name: "Master password",
+		ok: false,
+		fix: "bwx config master-password",
+	};
+}
+
+async function checkConfigDir(): Promise<Check> {
+	const configDir =
+		process.env.XDG_CONFIG_HOME ?? `${process.env.HOME}/.config`;
+	const dir = `${configDir}/bwx`;
+	try {
+		const { accessSync, constants } = await import("node:fs");
+		accessSync(dir, constants.W_OK);
+		return { name: "Config directory", ok: true, detail: dir };
+	} catch {}
+	return {
+		name: "Config directory",
+		ok: false,
+		detail: dir,
+		fix: `mkdir -p ${dir}`,
+	};
+}

package/src/cli/commands/get.ts

@@ -1,47 +1,142 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
 import { emitData } from "../io.ts";
-import { handleFatalError } from "../io.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
+import { BW_TYPE_LABELS, BwItemSchema } from "../../bw/types.ts";
+import pc from "picocolors";
 
-const VALID_FIELDS = ["password", "username", "totp", "notes", "uri", "item"];
+const BUILTIN_FIELDS = ["password", "username", "totp", "notes", "uri", "item"];
 
 export function registerGet(program: Command): void {
 	program
 		.command("get")
-		.description("Get a field from a vault item")
-		.argument("<field>", `Field: ${VALID_FIELDS.join(" | ")}`)
+		.description("Get a field from a vault item (built-in or custom)")
+		.argument("<field>", "Field: password | username | totp | notes | uri | item | <custom>")
 		.argument("<item>", "Item name or ID")
 		.action(async function (this: Command, field: string, item: string) {
 			const opts = getGlobalOpts(this);
 
-			if (!VALID_FIELDS.includes(field)) {
-				throw new CliError(
-					`Invalid field "${field}". Valid: ${VALID_FIELDS.join(", ")}`,
-					ExitCode.BadArgs,
-				);
-			}
-
-			const result = await withSession(opts, async () => {
-				if (field === "item") {
-					return runBwOrThrow(["get", "item", item]);
-				}
-				return runBwOrThrow(["get", field, item]);
-			});
-
-			if (!result) {
-				throw new CliError(
-					`No ${field} found for item: ${item}`,
-					ExitCode.NotFound,
-				);
+			if (BUILTIN_FIELDS.includes(field)) {
+				await getBuiltinField(field, item, opts);
+			} else {
+				await getCustomField(field, item, opts);
 			}
+		});
+}
 
+async function getBuiltinField(
+	field: string,
+	item: string,
+	opts: ReturnType<typeof getGlobalOpts>,
+): Promise<void> {
+	try {
+		const result = await withSession(opts, async () => {
 			if (field === "item") {
-				emitData(JSON.parse(result), opts);
-			} else {
-				emitData(result, opts);
+				return runBwOrThrow(["get", "item", item]);
 			}
+			return runBwOrThrow(["get", field, item]);
 		});
+
+		if (!result) {
+			throw new CliError(
+				`No ${field} found for item: ${item}`,
+				ExitCode.NotFound,
+			);
+		}
+
+		if (field === "item") {
+			emitData(JSON.parse(result), opts);
+		} else {
+			emitData(result, opts);
+		}
+	} catch (err) {
+		if (
+			err instanceof CliError &&
+			/more than one result/i.test(err.message)
+		) {
+			const matches = await resolveAmbiguous(item);
+			throw new CliError(
+				formatAmbiguousError(item, matches, opts),
+				ExitCode.BadArgs,
+			);
+		}
+		throw err;
+	}
+}
+
+async function getCustomField(
+	fieldName: string,
+	item: string,
+	opts: ReturnType<typeof getGlobalOpts>,
+): Promise<void> {
+	const json = await withSession(opts, () =>
+		runBwOrThrow(["get", "item", item]),
+	);
+
+	const parsed = BwItemSchema.parse(JSON.parse(json));
+	const fields = parsed.fields ?? [];
+	const match = fields.find((f) => f.name === fieldName);
+
+	if (!match) {
+		const available = fields.map((f) => f.name).join(", ");
+		const msg = available
+			? `Field "${fieldName}" not found. Available: ${available}`
+			: `Field "${fieldName}" not found (item has no custom fields)`;
+		throw new CliError(msg, ExitCode.NotFound);
+	}
+
+	emitData(match.value ?? "", opts);
+}
+
+interface MatchInfo {
+	id: string;
+	name: string;
+	type: string;
+	username?: string;
+}
+
+async function resolveAmbiguous(query: string): Promise<MatchInfo[]> {
+	try {
+		const json = await runBwOrThrow([
+			"list",
+			"items",
+			"--search",
+			query,
+		]);
+		const items: Array<Record<string, unknown>> = JSON.parse(json);
+		return items.map((i) => ({
+			id: i.id as string,
+			name: i.name as string,
+			type: BW_TYPE_LABELS[i.type as number] ?? `type:${i.type}`,
+			username: (i.login as Record<string, unknown> | null)?.username as
+				| string
+				| undefined,
+		}));
+	} catch {
+		return [];
+	}
+}
+
+function formatAmbiguousError(
+	query: string,
+	matches: MatchInfo[],
+	opts: { json?: boolean },
+): string {
+	if (matches.length === 0) {
+		return `Multiple items match "${query}". Use a specific ID instead.`;
+	}
+
+	if (opts.json) {
+		return `Multiple items match "${query}": ${JSON.stringify(matches)}`;
+	}
+
+	const lines = [`Multiple items match "${query}":\n`];
+	for (const m of matches) {
+		const user = m.username ? ` (${m.username})` : "";
+		lines.push(`  ${pc.dim(m.id)}  ${pc.cyan(m.type)}  ${m.name}${pc.dim(user)}`);
+	}
+	lines.push(`\nUse a specific ID: ${pc.dim("bwx get <field> <id>")}`);
+	return lines.join("\n");
 }

package/src/cli/commands/list.ts

@@ -0,0 +1,81 @@
+import type { Command } from "commander";
+import { getGlobalOpts } from "../program.ts";
+import { emitData } from "../io.ts";
+import { CliError, ExitCode } from "../errors.ts";
+import { runBwOrThrow } from "../../bw/runner.ts";
+import { withSession } from "../../bw/session.ts";
+import { BW_TYPE_LABELS, BW_TYPE_FROM_NAME } from "../../bw/types.ts";
+import pc from "picocolors";
+
+export function registerList(program: Command): void {
+	program
+		.command("list")
+		.alias("ls")
+		.description("List all vault items")
+		.argument("[type]", "Filter by type: logins|notes|cards|identities")
+		.option("--folder <id>", "Filter by folder ID")
+		.option("--limit <n>", "Limit results", parseInt)
+		.action(async function (
+			this: Command,
+			type: string | undefined,
+			localOpts: { folder?: string; limit?: number },
+		) {
+			const opts = getGlobalOpts(this);
+
+			const args = ["list", "items"];
+			if (localOpts.folder) {
+				args.push("--folderid", localOpts.folder);
+			}
+
+			const json = await withSession(opts, () => runBwOrThrow(args));
+			let items: Array<Record<string, unknown>> = JSON.parse(json);
+
+			if (type) {
+				const typeVal = BW_TYPE_FROM_NAME[type];
+				if (typeVal === undefined) {
+					throw new CliError(
+						`Invalid type "${type}". Valid: logins, notes, cards, identities`,
+						ExitCode.BadArgs,
+					);
+				}
+				items = items.filter((i) => i.type === typeVal);
+			}
+
+			if (localOpts.limit && localOpts.limit > 0) {
+				items = items.slice(0, localOpts.limit);
+			}
+
+			if (items.length === 0) {
+				throw new CliError("No items found", ExitCode.NotFound);
+			}
+
+			if (opts.json) {
+				emitData(items, opts);
+				return;
+			}
+
+			if (opts.plain) {
+				for (const item of items) {
+					const t =
+						BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`;
+					const login = item.login as Record<string, unknown> | null;
+					const username = login?.username ?? "-";
+					process.stdout.write(
+						`${item.id}\t${t}\t${item.name}\t${username}\n`,
+					);
+				}
+				return;
+			}
+
+			for (const item of items) {
+				const t =
+					BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`;
+				const login = item.login as Record<string, unknown> | null;
+				const username = login?.username ?? "";
+				const userPart = username ? pc.dim(` (${username})`) : "";
+				process.stdout.write(
+					`${pc.dim(item.id as string)}  ${pc.cyan(t)}  ${item.name}${userPart}\n`,
+				);
+			}
+		});
+}

package/src/cli/commands/search.ts

@@ -9,7 +9,7 @@ import pc from "picocolors";
 
 export function registerSearch(program: Command): void {
 	program
-		.command("search")
+		.command("search").alias("find")
 		.description("Search vault items")
 		.argument("<query>", "Search query")
 		.option("--type <type>", "Filter by type: login|note|card|identity")

package/src/cli/program.ts

@@ -1,7 +1,6 @@
 import { Command } from "commander";
 import type { GlobalOptions } from "./types.ts";
 import { registerGet } from "./commands/get.ts";
-import { registerField } from "./commands/field.ts";
 import { registerSearch } from "./commands/search.ts";
 import { registerCreate } from "./commands/create.ts";
 import { registerEdit } from "./commands/edit.ts";
@@ -11,6 +10,8 @@ import { registerSync } from "./commands/sync.ts";
 import { registerUnlock } from "./commands/unlock.ts";
 import { registerLock } from "./commands/lock.ts";
 import { registerConfig } from "./commands/config.ts";
+import { registerDoctor } from "./commands/doctor.ts";
+import { registerList } from "./commands/list.ts";
 
 export function buildProgram(): Command {
 	const program = new Command();
@@ -18,7 +19,7 @@ export function buildProgram(): Command {
 	program
 		.name("bwx")
 		.description("Bitwarden Extended CLI")
-		.version("0.1.0")
+		.version("0.2.0")
 		.option("--json", "JSON output")
 		.option("--plain", "Plain parseable output")
 		.option("-q, --quiet", "Suppress log output")
@@ -33,13 +34,14 @@ export function buildProgram(): Command {
 	registerUnlock(program);
 	registerLock(program);
 	registerGet(program);
-	registerField(program);
 	registerSearch(program);
 	registerSync(program);
 	registerCreate(program);
 	registerEdit(program);
 	registerDelete(program);
+	registerList(program);
 	registerConfig(program);
+	registerDoctor(program);
 
 	return program;
 }

package/src/cli/commands/field.ts

@@ -1,36 +0,0 @@
-import type { Command } from "commander";
-import { getGlobalOpts } from "../program.ts";
-import { emitData } from "../io.ts";
-import { CliError, ExitCode } from "../errors.ts";
-import { runBwOrThrow } from "../../bw/runner.ts";
-import { withSession } from "../../bw/session.ts";
-import { BwItemSchema } from "../../bw/types.ts";
-
-export function registerField(program: Command): void {
-	program
-		.command("field")
-		.description("Get a custom field from a vault item")
-		.argument("<item>", "Item name or ID")
-		.argument("<field-name>", "Custom field name")
-		.action(async function (this: Command, item: string, fieldName: string) {
-			const opts = getGlobalOpts(this);
-
-			const json = await withSession(opts, () =>
-				runBwOrThrow(["get", "item", item]),
-			);
-
-			const parsed = BwItemSchema.parse(JSON.parse(json));
-			const fields = parsed.fields ?? [];
-			const match = fields.find((f) => f.name === fieldName);
-
-			if (!match) {
-				const available = fields.map((f) => f.name).join(", ");
-				const msg = available
-					? `Field "${fieldName}" not found. Available: ${available}`
-					: `Field "${fieldName}" not found (item has no custom fields)`;
-				throw new CliError(msg, ExitCode.NotFound);
-			}
-
-			emitData(match.value ?? "", opts);
-		});
-}