bwx 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,16 @@
 # bwx
 
-Bitwarden CLI wrapper for AI agents. Auto-unlock, session caching, structured output.
+Bitwarden CLI wrapper for AI agents (`bwx` = `bw extended`). Auto-unlock, session caching, structured output.
+
+> Currently macOS-only: `bwx` uses macOS Keychain for secure master password storage.
+
+## Platform support
+
+- ✅ macOS
+- ❌ Linux (not supported yet)
+- ❌ Windows (not supported yet)
+
+`bwx` relies on macOS Keychain for secure master-password storage and retrieval.
 
 ## Why
 
@@ -55,13 +65,15 @@ bwx doctor
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
 | `bwx field <item> <name>` | Get custom field by name |
 | `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`) |
+| `bwx attach list <item>` | List attachments for an item |
+| `bwx attach get <item> <attachment>` | Download attachment by ID or filename |
 
 ### Write
 
 | Command | Description |
 |---------|-------------|
-| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password`, `--uri`, `--field k=v`) |
-| `bwx edit <item>` | Edit item (`--name`, `--password`, `--add-field k=v`, `--rm-field name`) |
+| `bwx create` | Create item (`--type`, `--name`, `--username`, `--password-stdin`, `--field-file k=path`) |
+| `bwx edit <item>` | Edit item (`--name`, `--password-env`, `--add-field-file k=path`, `--rm-field name`) |
 | `bwx delete <item>` | Delete item (`--permanent`, `--force`) |
 
 ### Config
@@ -70,6 +82,36 @@ bwx doctor
 |---------|-------------|
 | `bwx config email [addr]` | Set account email |
 | `bwx config master-password` | Store master password in Keychain |
+| `bwx config list` / `bwx cfg ls` | Show config path + redacted content |
+
+### Attachments
+
+```bash
+bwx attach list "Apple Developer"
+bwx attach get "Apple Developer" "AuthKey.p8"
+bwx attach get "Apple Developer" "AuthKey.p8" --output ./secrets/
+```
+
+Aliases: `attach`, `attachment`, `attachments`; `list` also has `ls`.
+
+### Safe input
+
+Prefer stdin, files, or environment variables for secrets so values do not land in shell history.
+
+```bash
+printf '%s' "$TOKEN" | bwx create --type login --name "GitHub" --username user --password-stdin
+bwx edit "GitHub" --password-env GITHUB_TOKEN
+bwx create --name "Deploy key" --notes-file ./deploy-key.txt
+bwx create --name "Acme" --field-file '!API Key=./token.txt' --field-env account=ACME_ACCOUNT
+```
+
+Supported source flags:
+
+- Passwords: `--password-stdin`, `--password-file <path>`, `--password-env <name>`
+- Notes: `--notes-file <path>`
+- Create fields: `--field-file k=path`, `--field-env k=ENV`
+- Edit fields: `--add-field-file k=path`, `--add-field-env k=ENV`
+- Use `-` as the file path to read that source from stdin.
 
 ### Global flags
 
@@ -82,7 +124,7 @@ bwx doctor
 
 ## Custom fields
 
-Field syntax for `--field` / `--add-field`:
+Field syntax for `--field`, `--field-file`, `--field-env`, and edit variants:
 
 - `key=value` — text field
 - `!key=value` — hidden field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bwx",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "keywords": [
     "bitwarden",

package/src/bw/attachments.ts

@@ -0,0 +1,58 @@
+import { CliError, ExitCode } from "../cli/errors.ts";
+
+export interface AttachmentInfo {
+	id: string;
+	fileName: string;
+	size?: number;
+	sizeName?: string;
+}
+
+export function listAttachments(item: Record<string, unknown>): AttachmentInfo[] {
+	const raw = item.attachments;
+	if (!Array.isArray(raw)) return [];
+
+	return raw
+		.map((attachment) => normalizeAttachment(attachment))
+		.filter((attachment): attachment is AttachmentInfo => attachment !== null);
+}
+
+export function resolveAttachment(
+	attachments: AttachmentInfo[],
+	query: string,
+): AttachmentInfo {
+	const matches = attachments.filter(
+		(attachment) => attachment.id === query || attachment.fileName === query,
+	);
+
+	if (matches.length === 1) return matches[0]!;
+
+	if (matches.length > 1) {
+		throw new CliError(
+			`Multiple attachments match "${query}". Use an attachment ID instead.`,
+			ExitCode.BadArgs,
+		);
+	}
+
+	const available = attachments.map((attachment) => attachment.fileName).join(", ");
+	const suffix = available ? ` Available: ${available}` : "";
+	throw new CliError(`Attachment "${query}" not found.${suffix}`, ExitCode.NotFound);
+}
+
+function normalizeAttachment(value: unknown): AttachmentInfo | null {
+	if (!value || typeof value !== "object") return null;
+
+	const record = value as Record<string, unknown>;
+	if (typeof record.id !== "string" || typeof record.fileName !== "string") {
+		return null;
+	}
+
+	const attachment: AttachmentInfo = {
+		id: record.id,
+		fileName: record.fileName,
+	};
+
+	if (typeof record.size === "number") attachment.size = record.size;
+	if (typeof record.sizeName === "string") attachment.sizeName = record.sizeName;
+
+	return attachment;
+}

package/src/cli/commands/attach.ts

@@ -0,0 +1,112 @@
+import type { Command } from "commander";
+import pc from "picocolors";
+import { listAttachments, resolveAttachment } from "../../bw/attachments.ts";
+import { runBwOrThrow } from "../../bw/runner.ts";
+import { withSession } from "../../bw/session.ts";
+import { emitData, emitSuccess } from "../io.ts";
+import { getGlobalOpts } from "../program.ts";
+
+export function registerAttach(program: Command): void {
+	const attach = program
+		.command("attach")
+		.aliases(["attachment", "attachments"])
+		.description("List and download item attachments");
+
+	attach
+		.command("list")
+		.alias("ls")
+		.description("List attachments for an item")
+		.argument("<item>", "Item name or ID")
+		.action(async function (this: Command, item: string) {
+			const opts = getGlobalOpts(this);
+			const current = await getItem(item, opts);
+			const attachments = listAttachments(current);
+
+			if (opts.json) {
+				emitData(attachments, opts);
+				return;
+			}
+
+			if (opts.plain) {
+				for (const attachment of attachments) {
+					process.stdout.write(
+						[
+							attachment.id,
+							attachment.fileName,
+							attachment.sizeName ?? attachment.size ?? "-",
+						].join("\t") + "\n",
+					);
+				}
+				return;
+			}
+
+			if (attachments.length === 0) {
+				const itemName = typeof current.name === "string" ? current.name : item;
+				process.stdout.write(`No attachments on "${itemName}"\n`);
+				return;
+			}
+
+			for (const attachment of attachments) {
+				const size = attachment.sizeName ?? attachment.size;
+				const sizePart = size === undefined ? "" : pc.dim(` (${size})`);
+				process.stdout.write(
+					`${pc.dim(attachment.id)}  ${attachment.fileName}${sizePart}\n`,
+				);
+			}
+		});
+
+	attach
+		.command("get")
+		.description("Download an attachment from an item")
+		.argument("<item>", "Item name or ID")
+		.argument("<attachment>", "Attachment ID or filename")
+		.option("-o, --output <path>", "Output file or directory")
+		.action(async function (
+			this: Command,
+			item: string,
+			attachmentQuery: string,
+			localOpts: { output?: string },
+		) {
+			const opts = getGlobalOpts(this);
+			const current = await getItem(item, opts);
+			const attachments = listAttachments(current);
+			const attachment = resolveAttachment(attachments, attachmentQuery);
+			const itemId = String(current.id);
+			const output = localOpts.output ?? attachment.fileName;
+
+			await withSession(opts, () =>
+				runBwOrThrow([
+					"get",
+					"attachment",
+					attachment.id,
+					"--itemid",
+					itemId,
+					"--output",
+					output,
+				]),
+			);
+
+			const result = {
+				itemId,
+				attachmentId: attachment.id,
+				fileName: attachment.fileName,
+				output,
+			};
+
+			if (opts.json) {
+				emitData(result, opts);
+			} else if (opts.plain) {
+				emitData(output, opts);
+			} else {
+				emitSuccess(`Saved "${attachment.fileName}" to ${output}`, opts);
+			}
+		});
+}
+
+async function getItem(
+	item: string,
+	opts: ReturnType<typeof getGlobalOpts>,
+): Promise<Record<string, unknown>> {
+	const json = await withSession(opts, () => runBwOrThrow(["get", "item", item]));
+	return JSON.parse(json) as Record<string, unknown>;
+}

package/src/cli/commands/config.ts

@@ -1,8 +1,12 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitSuccess } from "../io.ts";
+import { emitData, emitSuccess } from "../io.ts";
 import { CliError, ExitCode } from "../errors.ts";
-import { loadConfig, saveConfig } from "../../config/store.ts";
+import {
+	getConfigPath,
+	loadConfig,
+	saveConfig,
+} from "../../config/store.ts";
 
 export function registerConfig(program: Command): void {
 	const configCmd = program
@@ -90,6 +94,72 @@ export function registerConfig(program: Command): void {
 
 			emitSuccess("Master password saved to Keychain", opts);
 		});
+
+	configCmd
+		.command("list").alias("ls")
+		.description("Show config file path and redacted content")
+		.action(async function (this: Command) {
+			const opts = getGlobalOpts(this);
+			const path = getConfigPath();
+			const file = Bun.file(path);
+			const exists = await file.exists();
+			let config: unknown = null;
+
+			if (exists) {
+				try {
+					config = JSON.parse(await file.text());
+				} catch (err) {
+					throw new CliError(
+						`Config file is not valid JSON: ${
+							err instanceof Error ? err.message : String(err)
+						}`,
+						ExitCode.Config,
+					);
+				}
+			}
+
+			emitData(
+				{
+					path,
+					exists,
+					config: redactSensitive(config),
+				},
+				opts,
+			);
+		});
+}
+
+const SENSITIVE_KEY_RE = [
+	/pass(word)?/i,
+	/secret/i,
+	/token/i,
+	/api[-_]?key/i,
+	/private/i,
+	/credential/i,
+	/session/i,
+	/auth/i,
+	/totp/i,
+];
+
+function redactSensitive(value: unknown): unknown {
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map((item) => redactSensitive(item));
+	}
+
+	const out: Record<string, unknown> = {};
+	for (const [key, current] of Object.entries(value)) {
+		out[key] = isSensitiveKey(key) ? "***REDACTED***" : redactSensitive(current);
+	}
+
+	return out;
+}
+
+function isSensitiveKey(key: string): boolean {
+	return SENSITIVE_KEY_RE.some((pattern) => pattern.test(key));
 }
 
 async function readLine(): Promise<string> {

package/src/cli/commands/create.ts

@@ -4,11 +4,29 @@ import { emitData, emitSuccess } from "../io.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
-import { buildNewItem, parseFieldFlag, bwEncode } from "../../bw/encoding.ts";
+import { buildNewItem, bwEncode } from "../../bw/encoding.ts";
+import {
+	assertSingleStdinSource,
+	collect,
+	listExplicitStdinInputs,
+	readOptionalStdin,
+	resolveFieldSources,
+	resolveItemTextInputs,
+	StdinReader,
+	type ItemTextInputs,
+} from "../input.ts";
 
-function collect(val: string, prev: string[]): string[] {
-	prev.push(val);
-	return prev;
+interface CreateOptions extends ItemTextInputs {
+	type: string;
+	name?: string;
+	username?: string;
+	uri: string[];
+	field: string[];
+	fieldFile: string[];
+	fieldEnv: string[];
+	folder?: string;
+	favorite?: boolean;
+	fromJson?: boolean;
 }
 
 export function registerCreate(program: Command): void {
@@ -18,44 +36,40 @@ export function registerCreate(program: Command): void {
 		.option("--type <type>", "Item type: login|note", "note")
 		.option("--name <name>", "Item name")
 		.option("--notes <text>", "Notes content")
+		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
 		.option("--username <user>", "Username (login type)")
 		.option("--password <pass>", "Password (login type)")
+		.option("--password-stdin", "Read password from stdin")
+		.option("--password-file <path>", "Read password from file (use - for stdin)")
+		.option("--password-env <name>", "Read password from environment variable")
 		.option("--uri <url>", "URI (repeatable)", collect, [])
 		.option("--field <kv>", "Custom field k=v (repeatable)", collect, [])
+		.option("--field-file <kv>", "Custom field value from file k=path (repeatable)", collect, [])
+		.option("--field-env <kv>", "Custom field value from env var k=ENV (repeatable)", collect, [])
 		.option("--folder <id>", "Folder ID")
 		.option("--favorite", "Mark as favorite")
 		.option("--from-json", "Read full item JSON from stdin")
 		.action(async function (
 			this: Command,
-			localOpts: {
-				type: string;
-				name?: string;
-				notes?: string;
-				username?: string;
-				password?: string;
-				uri: string[];
-				field: string[];
-				folder?: string;
-				favorite?: boolean;
-				fromJson?: boolean;
-			},
+			localOpts: CreateOptions,
 		) {
 			const opts = getGlobalOpts(this);
+			const stdin = new StdinReader();
 
 			let encoded: string;
 
 			if (localOpts.fromJson) {
-				const stdin = await readStdin();
-				if (!stdin) {
+				const stdinText = await stdin.read();
+				if (!stdinText) {
 					throw new CliError("No JSON provided on stdin", ExitCode.BadArgs);
 				}
 				// Validate it's JSON
 				try {
-					JSON.parse(stdin);
+					JSON.parse(stdinText);
 				} catch {
 					throw new CliError("Invalid JSON on stdin", ExitCode.BadArgs);
 				}
-				encoded = bwEncode(stdin);
+				encoded = bwEncode(stdinText);
 			} else {
 				if (!localOpts.name) {
 					throw new CliError("--name is required", ExitCode.BadArgs);
@@ -68,33 +82,41 @@ export function registerCreate(program: Command): void {
 					);
 				}
 
-				// Read notes from stdin if not provided and not a TTY
-				let notes = localOpts.notes ?? null;
-				if (notes === null && !process.stdin.isTTY) {
-					const stdinText = await readStdin();
-					if (stdinText) notes = stdinText;
-				}
+				const explicitStdinSources = listExplicitStdinInputs({
+					...localOpts,
+					fieldFileFlag: "--field-file",
+					fieldFiles: localOpts.fieldFile,
+				});
+				assertSingleStdinSource(explicitStdinSources);
+
+				const textInputs = await resolveItemTextInputs(localOpts, stdin);
+				let notes = textInputs.notes;
 
-				// Read password from stdin if not provided, login type, and not a TTY
-				let password = localOpts.password ?? null;
+				// Backward compatibility: piped create input becomes note content.
 				if (
-					password === null &&
-					localOpts.type === "login" &&
-					!process.stdin.isTTY &&
-					notes === null
+					notes === undefined &&
+					textInputs.password === undefined &&
+					explicitStdinSources.length === 0 &&
+					!process.stdin.isTTY
 				) {
-					const stdinText = await readStdin();
-					if (stdinText) password = stdinText;
+					notes = (await readOptionalStdin(stdin)) ?? undefined;
 				}
 
-				const fields = localOpts.field.map(parseFieldFlag);
+				const fields = await resolveFieldSources({
+					inline: localOpts.field,
+					file: localOpts.fieldFile,
+					env: localOpts.fieldEnv,
+					fileFlag: "--field-file",
+					envFlag: "--field-env",
+					stdin,
+				});
 
 				const item = buildNewItem({
 					type: localOpts.type,
 					name: localOpts.name,
-					notes,
+					notes: notes ?? null,
 					username: localOpts.username ?? null,
-					password,
+					password: textInputs.password ?? null,
 					uris: localOpts.uri,
 					fields,
 					folderId: localOpts.folder ?? null,
@@ -118,16 +140,3 @@ export function registerCreate(program: Command): void {
 			}
 		});
 }
-
-async function readStdin(): Promise<string | null> {
-	try {
-		const chunks: Uint8Array[] = [];
-		for await (const chunk of Bun.stdin.stream()) {
-			chunks.push(chunk);
-		}
-		const text = Buffer.concat(chunks).toString().trim();
-		return text || null;
-	} catch {
-		return null;
-	}
-}

package/src/cli/commands/edit.ts

@@ -4,11 +4,28 @@ import { emitData, emitSuccess } from "../io.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import { runBwOrThrow } from "../../bw/runner.ts";
 import { withSession } from "../../bw/session.ts";
-import { patchItem, parseFieldFlag, bwEncode } from "../../bw/encoding.ts";
+import { patchItem, bwEncode } from "../../bw/encoding.ts";
+import {
+	assertSingleStdinSource,
+	collect,
+	listExplicitStdinInputs,
+	resolveFieldSources,
+	resolveItemTextInputs,
+	StdinReader,
+	type ItemTextInputs,
+} from "../input.ts";
 
-function collect(val: string, prev: string[]): string[] {
-	prev.push(val);
-	return prev;
+interface EditOptions extends ItemTextInputs {
+	name?: string;
+	username?: string;
+	uri: string[];
+	addField: string[];
+	addFieldFile: string[];
+	addFieldEnv: string[];
+	rmField: string[];
+	folder?: string;
+	favorite?: boolean;
+	fromJson?: boolean;
 }
 
 export function registerEdit(program: Command): void {
@@ -18,10 +35,16 @@ export function registerEdit(program: Command): void {
 		.argument("<item>", "Item name or ID")
 		.option("--name <name>", "New name")
 		.option("--notes <text>", "New notes")
+		.option("--notes-file <path>", "Read notes from file (use - for stdin)")
 		.option("--username <user>", "New username")
 		.option("--password <pass>", "New password")
+		.option("--password-stdin", "Read password from stdin")
+		.option("--password-file <path>", "Read password from file (use - for stdin)")
+		.option("--password-env <name>", "Read password from environment variable")
 		.option("--uri <url>", "Set URIs (repeatable, replaces all)", collect, [])
 		.option("--add-field <kv>", "Add/update field k=v", collect, [])
+		.option("--add-field-file <kv>", "Add/update field value from file k=path", collect, [])
+		.option("--add-field-env <kv>", "Add/update field value from env var k=ENV", collect, [])
 		.option("--rm-field <name>", "Remove field by name", collect, [])
 		.option("--folder <id>", "Move to folder")
 		.option("--favorite", "Set favorite")
@@ -30,20 +53,10 @@ export function registerEdit(program: Command): void {
 		.action(async function (
 			this: Command,
 			item: string,
-			localOpts: {
-				name?: string;
-				notes?: string;
-				username?: string;
-				password?: string;
-				uri: string[];
-				addField: string[];
-				rmField: string[];
-				folder?: string;
-				favorite?: boolean;
-				fromJson?: boolean;
-			},
+			localOpts: EditOptions,
 		) {
 			const opts = getGlobalOpts(this);
+			const stdin = new StdinReader();
 
 			const result = await withSession(opts, async () => {
 				// Fetch current item
@@ -54,23 +67,38 @@ export function registerEdit(program: Command): void {
 				let encoded: string;
 
 				if (localOpts.fromJson) {
-					const chunks: Uint8Array[] = [];
-					for await (const chunk of Bun.stdin.stream()) {
-						chunks.push(chunk);
-					}
-					const stdinText = Buffer.concat(chunks).toString().trim();
+					const stdinText = await stdin.read();
 					if (!stdinText) {
 						throw new CliError("No JSON provided on stdin", ExitCode.BadArgs);
 					}
 					encoded = bwEncode(stdinText);
 				} else {
+					assertSingleStdinSource(
+						listExplicitStdinInputs({
+							...localOpts,
+							fieldFileFlag: "--add-field-file",
+							fieldFiles: localOpts.addFieldFile,
+						}),
+					);
+
+					const textInputs = await resolveItemTextInputs(localOpts, stdin);
+
+					const addFields = await resolveFieldSources({
+						inline: localOpts.addField,
+						file: localOpts.addFieldFile,
+						env: localOpts.addFieldEnv,
+						fileFlag: "--add-field-file",
+						envFlag: "--add-field-env",
+						stdin,
+					});
+
 					const patched = patchItem(current, {
 						name: localOpts.name,
-						notes: localOpts.notes,
+						notes: textInputs.notes,
 						username: localOpts.username,
-						password: localOpts.password,
+						password: textInputs.password,
 						uris: localOpts.uri.length > 0 ? localOpts.uri : undefined,
-						addFields: localOpts.addField.map(parseFieldFlag),
+						addFields,
 						rmFields: localOpts.rmField,
 						folderId: localOpts.folder,
 						favorite: localOpts.favorite,

package/src/cli/commands/get.ts

@@ -24,6 +24,16 @@ export function registerGet(program: Command): void {
 				await getCustomField(field, item, opts);
 			}
 		});
+
+	program
+		.command("field")
+		.description("Get a custom field from a vault item")
+		.argument("<item>", "Item name or ID")
+		.argument("<name>", "Custom field name")
+		.action(async function (this: Command, item: string, name: string) {
+			const opts = getGlobalOpts(this);
+			await getCustomField(name, item, opts);
+		});
 }
 
 async function getBuiltinField(

package/src/cli/input.ts

@@ -0,0 +1,248 @@
+import { parseFieldFlag, type ParsedField } from "../bw/encoding.ts";
+import { CliError, ExitCode } from "./errors.ts";
+
+export function collect(val: string, prev: string[]): string[] {
+	prev.push(val);
+	return prev;
+}
+
+/**
+ * Lazily reads stdin once. Commands validate that only one explicit stdin source
+ * is selected, but caching also keeps implicit legacy stdin reads predictable.
+ */
+export class StdinReader {
+	private textPromise: Promise<string> | null = null;
+
+	read(): Promise<string> {
+		this.textPromise ??= readStdinText();
+		return this.textPromise;
+	}
+}
+
+export interface TextSource {
+	label: string;
+	inline?: string;
+	stdin?: boolean;
+	file?: string;
+	env?: string;
+	flagNames: string[];
+	allowEmpty?: boolean;
+}
+
+export interface FieldSources {
+	inline: string[];
+	file: string[];
+	env: string[];
+	fileFlag: string;
+	envFlag: string;
+	stdin: StdinReader;
+}
+
+export interface ItemTextInputs {
+	notes?: string;
+	notesFile?: string;
+	password?: string;
+	passwordStdin?: boolean;
+	passwordFile?: string;
+	passwordEnv?: string;
+}
+
+export interface ResolvedItemTextInputs {
+	notes?: string;
+	password?: string;
+}
+
+export interface ExplicitStdinInputs extends ItemTextInputs {
+	fieldFileFlag?: string;
+	fieldFiles?: string[];
+}
+
+const NOTE_SOURCE_FLAGS = ["--notes", "--notes-file"];
+const PASSWORD_SOURCE_FLAGS = [
+	"--password",
+	"--password-stdin",
+	"--password-file",
+	"--password-env",
+];
+
+export async function resolveItemTextInputs(
+	inputs: ItemTextInputs,
+	stdin: StdinReader,
+): Promise<ResolvedItemTextInputs> {
+	assertSingleStdinSource(listExplicitStdinInputs(inputs));
+
+	const [notes, password] = await Promise.all([
+		resolveOptionalTextSource(
+			{
+				label: "notes",
+				inline: inputs.notes,
+				file: inputs.notesFile,
+				flagNames: NOTE_SOURCE_FLAGS,
+				allowEmpty: true,
+			},
+			stdin,
+		),
+		resolveOptionalTextSource(
+			{
+				label: "password",
+				inline: inputs.password,
+				stdin: inputs.passwordStdin,
+				file: inputs.passwordFile,
+				env: inputs.passwordEnv,
+				flagNames: PASSWORD_SOURCE_FLAGS,
+			},
+			stdin,
+		),
+	]);
+
+	return { notes, password };
+}
+
+export function listExplicitStdinInputs(inputs: ExplicitStdinInputs): string[] {
+	return [
+		inputs.notesFile === "-" ? "--notes-file -" : null,
+		inputs.passwordStdin ? "--password-stdin" : null,
+		inputs.passwordFile === "-" ? "--password-file -" : null,
+		...(inputs.fieldFileFlag && inputs.fieldFiles
+			? stdinSourcesForFieldFiles(inputs.fieldFileFlag, inputs.fieldFiles)
+			: []),
+	].filter((value): value is string => value !== null);
+}
+
+export async function resolveOptionalTextSource(
+	source: TextSource,
+	stdin: StdinReader,
+): Promise<string | undefined> {
+	const selected = [
+		source.inline !== undefined ? "inline" : null,
+		source.stdin ? "stdin" : null,
+		source.file !== undefined ? "file" : null,
+		source.env !== undefined ? "env" : null,
+	].filter((value): value is string => value !== null);
+
+	if (selected.length > 1) {
+		throw new CliError(
+			`Choose only one ${source.label} source: ${source.flagNames.join(", ")}`,
+			ExitCode.BadArgs,
+		);
+	}
+
+	if (selected.length === 0) return undefined;
+
+	let value: string;
+	if (source.inline !== undefined) {
+		value = source.inline;
+	} else if (source.stdin) {
+		value = await stdin.read();
+	} else if (source.file !== undefined) {
+		value = await readFileOrStdin(source.file, stdin, source.label);
+	} else {
+		value = readEnvValue(source.env!, source.label);
+	}
+
+	if (!source.allowEmpty && value.length === 0) {
+		throw new CliError(`${capitalize(source.label)} cannot be empty`, ExitCode.BadArgs);
+	}
+
+	return value;
+}
+
+export async function resolveFieldSources(
+	sources: FieldSources,
+): Promise<ParsedField[]> {
+	const fields = sources.inline.map(parseFieldFlag);
+
+	for (const raw of sources.file) {
+		const field = parseRequiredSourceField(raw, sources.fileFlag);
+		fields.push({
+			...field,
+			value: await readFileOrStdin(field.value, sources.stdin, field.name),
+		});
+	}
+
+	for (const raw of sources.env) {
+		const field = parseRequiredSourceField(raw, sources.envFlag);
+		fields.push({
+			...field,
+			value: readEnvValue(field.value, field.name),
+		});
+	}
+
+	return fields;
+}
+
+export function assertSingleStdinSource(sources: string[]): void {
+	if (sources.length <= 1) return;
+	throw new CliError(
+		`Only one stdin input source can be used at a time: ${sources.join(", ")}`,
+		ExitCode.BadArgs,
+	);
+}
+
+export function stdinSourcesForFieldFiles(flag: string, raws: string[]): string[] {
+	return raws
+		.filter((raw) => parseRequiredSourceField(raw, flag).value === "-")
+		.map((raw) => `${flag} ${raw}`);
+}
+
+export async function readOptionalStdin(stdin: StdinReader): Promise<string | null> {
+	const text = await stdin.read();
+	return text.length > 0 ? text : null;
+}
+
+function parseRequiredSourceField(raw: string, flag: string): ParsedField {
+	if (!raw.includes("=")) {
+		throw new CliError(`Expected ${flag} k=value`, ExitCode.BadArgs);
+	}
+
+	const field = parseFieldFlag(raw);
+	if (field.value.length === 0) {
+		throw new CliError(`Expected ${flag} ${field.name}=value`, ExitCode.BadArgs);
+	}
+
+	return field;
+}
+
+async function readFileOrStdin(
+	path: string,
+	stdin: StdinReader,
+	label: string,
+): Promise<string> {
+	if (path === "-") return stdin.read();
+
+	try {
+		return stripFinalNewline(await Bun.file(path).text());
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new CliError(
+			`Failed to read ${label} from "${path}": ${message}`,
+			ExitCode.BadArgs,
+		);
+	}
+}
+
+function readEnvValue(name: string, label: string): string {
+	if (!Object.prototype.hasOwnProperty.call(process.env, name)) {
+		throw new CliError(
+			`Environment variable ${name} is not set for ${label}`,
+			ExitCode.BadArgs,
+		);
+	}
+	return process.env[name] ?? "";
+}
+
+async function readStdinText(): Promise<string> {
+	const chunks: Uint8Array[] = [];
+	for await (const chunk of Bun.stdin.stream()) {
+		chunks.push(chunk);
+	}
+	return stripFinalNewline(Buffer.concat(chunks).toString());
+}
+
+function stripFinalNewline(text: string): string {
+	return text.replace(/\r?\n$/, "");
+}
+
+function capitalize(value: string): string {
+	return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/src/cli/program.ts

@@ -12,6 +12,7 @@ import { registerLock } from "./commands/lock.ts";
 import { registerConfig } from "./commands/config.ts";
 import { registerDoctor } from "./commands/doctor.ts";
 import { registerList } from "./commands/list.ts";
+import { registerAttach } from "./commands/attach.ts";
 
 export function buildProgram(): Command {
 	const program = new Command();
@@ -19,7 +20,7 @@ export function buildProgram(): Command {
 	program
 		.name("bwx")
 		.description("Bitwarden Extended CLI")
-		.version("0.2.0")
+		.version("0.3.0")
 		.option("--json", "JSON output")
 		.option("--plain", "Plain parseable output")
 		.option("-q, --quiet", "Suppress log output")
@@ -39,6 +40,7 @@ export function buildProgram(): Command {
 	registerCreate(program);
 	registerEdit(program);
 	registerDelete(program);
+	registerAttach(program);
 	registerList(program);
 	registerConfig(program);
 	registerDoctor(program);

package/src/config/store.ts

@@ -4,6 +4,10 @@ const CONFIG_DIR =
 	process.env.XDG_CONFIG_HOME ?? `${process.env.HOME}/.config`;
 const CONFIG_PATH = `${CONFIG_DIR}/bwx/config.json`;
 
+export function getConfigPath(): string {
+	return CONFIG_PATH;
+}
+
 export async function loadConfig(): Promise<Config> {
 	try {
 		const text = await Bun.file(CONFIG_PATH).text();

package/src/index.ts

@@ -7,25 +7,35 @@ import type { GlobalOptions } from "./cli/types.ts";
 export async function main(argv: string[]): Promise<void> {
 	const program = buildProgram();
 
-	// Parse global opts early for error formatting
-	let opts: GlobalOptions = {};
-	try {
-		program.parseOptions(argv.slice(2));
-		const rawOpts = program.opts();
-		opts = {
-			json: rawOpts.json ?? false,
-			plain: rawOpts.plain ?? false,
-			quiet: rawOpts.quiet ?? false,
-			verbose: rawOpts.verbose ?? false,
-		};
-	} catch {
-		// Fall through — full parse below will handle
+	// Bare invocation should show top-level help.
+	if (argv.length <= 2) {
+		program.outputHelp();
+		return;
 	}
 
+	// Parse global opts early for error formatting
+	const opts = parseGlobalOpts(argv.slice(2));
+
 	try {
 		await program.parseAsync(argv);
 	} catch (err) {
 		if (err instanceof CommanderError) {
+			if (err.code === "commander.help") {
+				const helpArgv = [...argv, "--help"];
+				try {
+					await program.parseAsync(helpArgv);
+				} catch (helpErr) {
+					if (
+						!(
+							helpErr instanceof CommanderError &&
+							helpErr.code === "commander.helpDisplayed"
+						)
+					) {
+						throw helpErr;
+					}
+				}
+				process.exit(err.exitCode);
+			}
 			if (err.exitCode === 0) process.exit(0); // --help, --version
 			// Commander prefixes messages with "error: " — strip it
 			const msg = err.message.replace(/^error:\s*/i, "");
@@ -34,3 +44,12 @@ export async function main(argv: string[]): Promise<void> {
 		handleFatalError(err, opts);
 	}
 }
+
+function parseGlobalOpts(args: string[]): GlobalOptions {
+	return {
+		json: args.includes("--json"),
+		plain: args.includes("--plain"),
+		quiet: args.includes("-q") || args.includes("--quiet"),
+		verbose: args.includes("-v") || args.includes("--verbose"),
+	};
+}