bwx 0.6.3 → 0.8.0

package/README.md

@@ -69,9 +69,10 @@ unlock. `valid` means reads work now, `stale` means the cached session was rejec
 
 | Command | Description |
 |---------|-------------|
-| `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
+| `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`), `--raw` |
 | `bwx get totp <item>` | TOTP code (`--fresh [n]`, `--seed`) |
-| `bwx field <name> <item>` | Get custom field by name (same argument order as `get`) |
+| `bwx get <card field> <item>` | Card field (`number`, `cvv`, `cardholder`, `brand`, `expiry`, …) |
+| `bwx field <name> <item>` | Get custom field by name (same argument order as `get`), `--raw` |
 | `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
 | `bwx list [type]` | List items (`--type`, `--folder`, `--limit`, `--full-items`) |
 | `bwx folders` | List folder names and IDs |
@@ -103,6 +104,29 @@ error: No item matching "GitHub PAT vforsh old". Did you mean:
   3683fb9a-…  note  GitHub PAT (yaforsh) [codex-monitor-pr]
 ```
 
+### Piping a secret
+
+`get` and `field` end their output with a newline, which reads fine in a terminal and
+lands *inside the secret* for a consumer that treats stdin literally. `--raw` suppresses
+that one newline — and only that one: newlines stored in the value are its own and are
+written through.
+
+```bash
+bwx get password "GitHub" --raw | argus fill app --selector 'input[type=password]' --value-stdin
+```
+
+`--raw` values are byte-for-byte, so whitespace around a password survives too (the
+default output trims it). `--raw` and `--json` are mutually exclusive — the JSON envelope
+quotes and wraps the value, so there is no raw byte stream to hand over — and combining
+them is a usage error rather than a silent winner.
+
+For handing a secret to a whole command rather than to one stdin, `bwx run` keeps it out
+of argv entirely:
+
+```bash
+bwx run --env GITHUB_TOKEN=password:"GitHub PAT" -- gh api /user
+```
+
 ### TOTP
 
 Codes are computed locally from the stored secret. A TOTP therefore costs no extra `bw`
@@ -139,6 +163,45 @@ Spaces, hyphens, and `=` padding are stripped and case is normalized; an `otpaut
 is stored verbatim so its parameters survive. Malformed secrets are rejected before the
 write, because a bad seed is otherwise discovered at the login it was supposed to unlock.
 
+### Cards
+
+Card items keep their values in a `card` object that `bw get <field>` cannot reach, so
+bwx reads them from the item itself — one vault read, no extra `bw` spawn:
+
+```bash
+bwx get number "Visa"        # 4111111111111111
+bwx get cvv "Visa"           # 123
+bwx get cardholder "Visa"    # Vladislav Forsh
+bwx get brand "Visa"         # Visa
+bwx get expiry "Visa"        # 03/2030
+bwx get expMonth "Visa"      # 03
+bwx get expYear "Visa"       # 2030
+```
+
+Names match leniently on case, dashes, and underscores, and bw's own JSON keys work too,
+so a name copied out of `bwx get item` resolves (`code` → `cvv`, `cardholderName` →
+`cardholder`, `exp-month` → `expMonth`).
+
+Two values are normalized rather than passed through, because the stored form is not the
+usable one:
+
+- `expMonth` is zero-padded — bw stores the month as typed (`3`), and every `MM` field
+  wants `03`.
+- `expiry` is composed from month and year, and is withheld entirely if either is missing
+  rather than handing back half a date.
+
+A card field only means the card object **on a card item**. `number`, `code`, and `brand`
+are plausible custom field names, so on any other item type they resolve as custom fields
+exactly as before — and if no such custom field exists, the error says which kind of item
+it actually is. `bwx field` is unchanged: custom fields only, never a card field.
+
+Grouping several card fields into one read is worth it — see [Secrets into a child
+process](#secrets-into-a-child-process):
+
+```bash
+bwx run --env NUM=number:Visa --env CVV=cvv:Visa --env EXP=expiry:Visa -- ./pay.sh
+```
+
 ### Listings are capped
 
 Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,

package/package.json

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

package/skill/bwx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bwx
-description: Bitwarden Extended CLI — retrieve, create, edit, delete vault items with auto-unlock. Use when the agent needs passwords, API keys, TOTP codes, custom fields, or vault management. Triggers on mentions of Bitwarden, bw, bwx, vault, password, secrets, TOTP, save key/token.
+description: Bitwarden Extended CLI — retrieve, create, edit, delete vault items with auto-unlock. Use when the agent needs passwords, API keys, TOTP codes, card details, custom fields, or vault management. Triggers on mentions of Bitwarden, bw, bwx, vault, password, secrets, TOTP, card number, CVV, save key/token.
 ---
 
 # bwx
@@ -17,8 +17,10 @@ bwx get username "GitHub"               # username
 bwx get notes "Deploy key"              # secure note content
 bwx get uri "GitHub"                    # first URI
 bwx get item "GitHub"                   # full item JSON
+bwx get number "Visa"                   # card number (also: cvv, expiry, cardholder, brand)
 bwx get "API Key" "Acme"                # custom field by name
 bwx field "API Key" "Acme"              # custom-field-only lookup, same arg order
+bwx get password "GitHub" --raw         # no trailing newline, for piping into stdin
 
 bwx search github                       # fuzzy search, human table
 bwx search github --json                # id/type/name/username only — no secrets
@@ -45,6 +47,7 @@ echo "secret" | bwx create --name "Piped Note"
 ### `bwx get <field> <item>`
 
 Built-in fields: `password | username | totp | notes | uri | item`.
+Card items additionally take `number | cvv | cardholder | brand | expiry | expMonth | expYear`.
 Anything else is looked up as a custom field. Lists available fields on miss.
 
 A miss suggests near matches; an ambiguous name lists candidates with IDs. Read the
@@ -76,6 +79,43 @@ exactly are delegated to `bw get totp` instead of guessed at.
 Custom fields only, so an item whose custom field is named `password` is still reachable.
 Takes its arguments in the same order as `get` (this changed in 0.5.0).
 
+### `--raw` (on `get` and `field`)
+
+Output normally ends in a newline, which a consumer that reads stdin literally takes as
+the last byte of the secret. `--raw` suppresses that one newline and nothing else —
+newlines inside the value are written through, and the value is byte-for-byte, so
+surrounding whitespace survives (the default output trims it).
+
+```bash
+bwx get password "GitHub" --raw | argus fill app --selector 'input[type=password]' --value-stdin
+```
+
+Prefer this over `$(bwx get …)` when piping a secret: command substitution eats trailing
+newlines *and* puts the secret in the child's argv, where any same-user process can read
+it. `--raw` and `--json` cannot be combined (the envelope quotes and wraps the value); use
+`bwx run --env` when a whole command needs the secret in its environment instead.
+
+### Card fields
+
+```bash
+bwx get number "Visa"        # 4111111111111111
+bwx get cvv "Visa"           # 123        (bw's own key `code` works too)
+bwx get cardholder "Visa"    # Vladislav Forsh
+bwx get brand "Visa"         # Visa
+bwx get expiry "Visa"        # 03/2030    (composed; withheld if either half is missing)
+bwx get expMonth "Visa"      # 03         (zero-padded; bw stores "3")
+bwx get expYear "Visa"       # 2030
+```
+
+Read from the fetched item — `bw` has no card fields — so they cost one vault read and
+batch with each other under `bwx run`. Names match leniently on case, dashes, and
+underscores, and bw's JSON keys resolve (`code`, `cardholderName`, `exp-month`).
+
+A card field means the card object **only on a card item**. On any other type it resolves
+as a custom field of that name, since `number` and `code` are ordinary field names; the
+error names the item's actual type when no such field exists. `bwx field` never returns a
+card field.
+
 ### `bwx search <query>` / `bwx list [type]`
 
 Flags: `--type login|note|card|identity`, `--folder <name|id>`, `--limit <n>`, `--full-items`
@@ -108,7 +148,7 @@ bwx run --env DB_PASS=password:'Prod DB' -- ./migrate.sh
 bwx run --env TOKEN='API Key:Acme' --env USER=username:Acme -- ./deploy.sh
 ```
 
-- `--env` is repeatable; the field resolves as in `bwx get` (built-in, else custom field).
+- `--env` is repeatable; the field resolves as in `bwx get` (built-in, else card, else custom field).
 - Only the first `:` splits field from item, so `password:http://my.router` works.
 - Put `--` before the command when it takes its own flags.
 - Child stdio is inherited; bwx exits with the child's status (`128 + signal` if killed).

package/src/bw/cards.ts

@@ -0,0 +1,116 @@
+import type { BwCard } from "./types.ts";
+
+/**
+ * Card items keep their values in a `card` object rather than in `login` or in
+ * custom fields, and `bw get <field>` has no equivalent for any of them — so
+ * these names are resolved here, from an item bwx has already fetched.
+ *
+ * A reader returns the value or `null`; naming the item and raising is the
+ * caller's job, since it holds the item name and the error type.
+ */
+type CardReader = (card: BwCard) => string | null;
+
+/** Canonical names, in the order help text and errors list them. */
+export const CARD_FIELDS = [
+	"number",
+	"cvv",
+	"cardholder",
+	"brand",
+	"expiry",
+	"expMonth",
+	"expYear",
+] as const;
+
+export type CardField = (typeof CARD_FIELDS)[number];
+
+/**
+ * How each canonical field reads off the card object. Keyed by `CardField`, so
+ * adding a name to {@link CARD_FIELDS} without a reader fails to compile rather
+ * than at the one call that asks for it.
+ */
+const CARD_READERS: Record<CardField, CardReader> = {
+	number: (card) => text(card.number),
+	cvv: (card) => text(card.code),
+	cardholder: (card) => text(card.cardholderName),
+	brand: (card) => text(card.brand),
+	expiry: readExpiry,
+	expMonth: readExpMonth,
+	expYear: (card) => text(card.expYear),
+};
+
+/**
+ * Other spellings of the same fields: bw's own JSON keys, so a name copied out
+ * of `bwx get item` resolves, plus the words people reach for first.
+ */
+const CARD_ALIASES: Record<string, CardField> = {
+	code: "cvv",
+	cvc: "cvv",
+	securityCode: "cvv",
+	cardholderName: "cardholder",
+	holder: "cardholder",
+	exp: "expiry",
+	expiration: "expiry",
+};
+
+/**
+ * Card names are matched leniently — case, dashes, and underscores all collapse
+ * — because `expMonth`, `exp-month`, and `expmonth` are the same request, and
+ * failing one of them would only teach the caller to try the other two.
+ */
+function normalize(field: string): string {
+	return field.toLowerCase().replaceAll(/[-_\s]/g, "");
+}
+
+/**
+ * Every accepted spelling to its canonical field, derived so that the two
+ * tables above stay the only place a card field name is written down.
+ */
+const CANONICAL_BY_SPELLING: Record<string, CardField> = {
+	...Object.fromEntries(CARD_FIELDS.map((field) => [normalize(field), field])),
+	...Object.fromEntries(
+		Object.entries(CARD_ALIASES).map(([alias, field]) => [normalize(alias), field]),
+	),
+};
+
+/** True when `field` names a card field rather than a login field or a custom one. */
+export function isCardField(field: string): boolean {
+	return normalize(field) in CANONICAL_BY_SPELLING;
+}
+
+/** Reads one card field, or `null` when the card carries no value for it. */
+export function readCardValue(card: BwCard, field: string): string | null {
+	const canonical = CANONICAL_BY_SPELLING[normalize(field)];
+	return canonical ? CARD_READERS[canonical](card) : null;
+}
+
+/**
+ * bw stores the month as the digit it was entered as ("3"), which is not what a
+ * `MM` field or an expiry string wants. Padding here means every consumer gets
+ * the two-digit form rather than each one remembering to pad.
+ */
+function readExpMonth(card: BwCard): string | null {
+	return text(card.expMonth)?.padStart(2, "0") ?? null;
+}
+
+/**
+ * Composed rather than stored: Bitwarden keeps month and year apart, and a
+ * caller filling one expiry box should not have to join them itself. The year
+ * is passed through as stored, so a vault holding `30` yields `03/30`.
+ */
+function readExpiry(card: BwCard): string | null {
+	const month = readExpMonth(card);
+	const year = text(card.expYear);
+	// Half an expiry is worse than none — it would read as a complete date.
+	return month && year ? `${month}/${year}` : null;
+}
+
+/**
+ * Normalizes a stored value to a non-empty string. Months and years arrive as
+ * either strings or numbers depending on how the item was created, and an empty
+ * string means "not set" just as much as `null` does.
+ */
+function text(value: string | number | null | undefined): string | null {
+	if (value === null || value === undefined) return null;
+	const trimmed = String(value).trim();
+	return trimmed === "" ? null : trimmed;
+}

package/src/bw/fields.ts

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { CliError, ExitCode } from "../cli/errors.ts";
 import type { GlobalOptions } from "../cli/types.ts";
+import { isCardField, readCardValue, CARD_FIELDS } from "./cards.ts";
 import { summarizeItem, type ItemSummary } from "./items.ts";
 import { runBwOrThrow } from "./runner.ts";
 import { withSession } from "./session.ts";
@@ -12,10 +13,10 @@ import {
 	TotpUnsupportedError,
 	type TotpCode,
 } from "./totp.ts";
-import { BwItemSchema, type BwItem } from "./types.ts";
+import { BwItemSchema, BwItemType, itemTypeLabel, type BwItem } from "./types.ts";
 
-/** Fields `bw get` resolves natively; anything else is a custom field name. */
-const BUILTIN_FIELDS = [
+/** Fields `bw get` resolves natively; anything else is a card or custom field. */
+export const BUILTIN_FIELDS = [
 	"password",
 	"username",
 	"totp",
@@ -39,6 +40,14 @@ export interface ReadFieldOptions {
 	 * field is called e.g. `password` is still reachable.
 	 */
 	customOnly?: boolean;
+	/**
+	 * Return the value exactly as stored rather than trimmed. Only `bwx get --raw`
+	 * asks for this; every other caller compares or parses the value, where
+	 * surrounding whitespace is framing rather than content. Custom and card
+	 * fields are read out of the item JSON and are verbatim either way — this
+	 * reaches the fields `bw get <field>` prints on stdout.
+	 */
+	verbatim?: boolean;
 }
 
 /**
@@ -71,8 +80,16 @@ export async function readItemField(
 			return (await nextCode()).code;
 		}
 
-		return isBuiltinField(field) && !options?.customOnly
-			? readBuiltinField(field, item, opts)
+		if (options?.customOnly) return readCustomField(field, item, opts);
+
+		// `bw get` has no card fields, so they are read from the item itself —
+		// which also settles whether this item is a card at all.
+		if (isCardField(field)) {
+			return extractField(await fetchItem(item, opts), field, options);
+		}
+
+		return isBuiltinField(field)
+			? readBuiltinField(field, item, opts, options?.verbatim)
 			: readCustomField(field, item, opts);
 	});
 }
@@ -266,7 +283,19 @@ function extractField(
 	field: string,
 	options?: ReadFieldOptions,
 ): string {
-	if (!isBuiltinField(field) || options?.customOnly) {
+	if (options?.customOnly) return pickCustomField(item, field);
+
+	// A card field only means the card object on a card item. On anything else
+	// `number` or `code` is just a custom field name, and stealing it here would
+	// break lookups that worked before cards were understood at all — so the
+	// name is resolved as one, and the miss says what the item actually is.
+	if (isCardField(field)) {
+		return item.type === BwItemType.Card
+			? extractCardField(item, field)
+			: pickCustomField(item, field, cardFieldHint(item, field));
+	}
+
+	if (!isBuiltinField(field)) {
 		return pickCustomField(item, field);
 	}
 
@@ -274,7 +303,7 @@ function extractField(
 
 	// Named exhaustively rather than defaulted: a chain ending in `password`
 	// would hand back the password for any field it failed to recognize.
-	let value: string | null;
+	let value: string | null | undefined;
 	switch (field) {
 		case "notes":
 			value = item.notes;
@@ -309,9 +338,10 @@ async function readBuiltinField(
 	field: string,
 	item: string,
 	opts: GlobalOptions,
+	verbatim = false,
 ): Promise<string> {
 	const result = await withSession(opts, () =>
-		runBwOrThrow(["get", field, item]),
+		runBwOrThrow(["get", field, item], { verbatim }),
 	);
 
 	if (!result) {
@@ -332,16 +362,35 @@ async function readCustomField(
 	return pickCustomField(await fetchItem(item, opts), fieldName);
 }
 
-function pickCustomField(item: BwItem, fieldName: string): string {
+function extractCardField(item: BwItem, field: string): string {
+	const value = item.card ? readCardValue(item.card, field) : null;
+	if (!value) {
+		throw new FieldMissingError(
+			`No ${field} found for item: ${item.name}`,
+			ExitCode.NotFound,
+		);
+	}
+
+	return value;
+}
+
+/** Why a card field found nothing on an item that is not a card. */
+function cardFieldHint(item: BwItem, field: string): string {
+	return `Note: "${field}" reads a card field on card items, but "${item.name}" is a ${itemTypeLabel(item.type)} item. Card fields: ${CARD_FIELDS.join(", ")}.`;
+}
+
+/** `hint` is appended to a miss, for a name that could have meant something else. */
+function pickCustomField(item: BwItem, fieldName: string, hint?: string): string {
 	const fields = item.fields ?? [];
 	const match = fields.find((f) => f.name === fieldName);
 
 	if (!match) {
 		const available = fields.map((f) => f.name).join(", ");
+		const miss = available
+			? `Field "${fieldName}" not found. Available: ${available}`
+			: `Field "${fieldName}" not found (item has no custom fields)`;
 		throw new FieldMissingError(
-			available
-				? `Field "${fieldName}" not found. Available: ${available}`
-				: `Field "${fieldName}" not found (item has no custom fields)`,
+			hint ? `${miss}\n\n${hint}` : miss,
 			ExitCode.NotFound,
 		);
 	}

package/src/bw/items.ts

@@ -1,4 +1,4 @@
-import { BW_TYPE_LABELS } from "./types.ts";
+import { itemTypeLabel } from "./types.ts";
 
 /**
  * The only shape of a vault item bwx prints when the caller did not ask for a
@@ -25,7 +25,7 @@ export function summarizeItem(item: Record<string, unknown>): ItemSummary {
 
 	return {
 		id: String(item.id ?? ""),
-		type: BW_TYPE_LABELS[item.type as number] ?? `type:${item.type}`,
+		type: itemTypeLabel(item.type as number),
 		name: String(item.name ?? ""),
 		username: typeof username === "string" && username ? username : null,
 		hasTotp: typeof totp === "string" && totp.length > 0,

package/src/bw/runner.ts

@@ -11,6 +11,13 @@ export interface RunBwOptions {
 	/** Explicit session, or `null` to run without one (login/unlock/status). */
 	session?: string | null;
 	env?: Record<string, string>;
+	/**
+	 * Return stdout as `bw` wrote it, less the single newline `bw` adds to frame
+	 * its own output. The default trim is right for values bwx parses or compares
+	 * and wrong for a secret handed back byte-for-byte: whitespace around a
+	 * password belongs to the password.
+	 */
+	verbatim?: boolean;
 }
 
 /** Deadline for a single `bw` call; overridable with `--timeout`. */
@@ -66,7 +73,11 @@ export async function runBw(
 			);
 		}
 
-		return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+		return {
+			stdout: options?.verbatim ? unframe(stdout) : stdout.trim(),
+			stderr: stderr.trim(),
+			exitCode,
+		};
 	} finally {
 		guard?.disarm();
 	}
@@ -87,6 +98,11 @@ export async function runBwOrThrow(
 	return result.stdout;
 }
 
+/** Drops the one newline `bw` prints after a value, and nothing the value owns. */
+function unframe(stdout: string): string {
+	return stdout.replace(/\r?\n$/, "");
+}
+
 /**
  * Child environment for `bw`. `BW_SESSION` is set from our session, or removed
  * outright so an ambient one from the caller's shell cannot silently substitute

package/src/bw/types.ts

@@ -30,6 +30,11 @@ export const BW_TYPE_LABELS: Record<number, string> = {
 	4: "identity",
 };
 
+/** The label for an item type, naming the raw number for one bwx predates. */
+export function itemTypeLabel(type: number): string {
+	return BW_TYPE_LABELS[type] ?? `type:${type}`;
+}
+
 export const BW_TYPE_FROM_NAME: Record<string, BwItemType> = {
 	login: BwItemType.Login,
 	logins: BwItemType.Login,
@@ -73,17 +78,43 @@ export interface BwLogin {
 	uris: BwUri[] | null;
 }
 
+// --- Card ---
+
+/**
+ * Values arrive as strings from `bw`, but `expMonth`/`expYear` are numbers in
+ * some hand-written and imported items, so both are accepted rather than
+ * failing the whole item parse over a field the caller may not even want. Every
+ * key is optional for the same reason — see the schema below.
+ */
+export interface BwCard {
+	cardholderName?: string | null;
+	brand?: string | null;
+	number?: string | null;
+	expMonth?: string | number | null;
+	expYear?: string | number | null;
+	code?: string | null;
+}
+
 // --- Item (loose schema — passthrough for edit round-trip) ---
 
+/**
+ * `bw get item` omits keys it has no value for rather than nulling them — an
+ * unfiled card has no `folderId`, a login without 2FA no `totp` — so every key
+ * but an item's identity is optional as well as nullable. Requiring them made
+ * an absent key fail the parse and took down reads of the fields that were
+ * present.
+ */
+const OmittableTextSchema = z.string().nullable().optional();
+
 export const BwItemSchema = z
 	.object({
 		id: z.string(),
-		organizationId: z.string().nullable(),
-		folderId: z.string().nullable(),
+		organizationId: OmittableTextSchema,
+		folderId: OmittableTextSchema,
 		type: z.number(),
 		name: z.string(),
-		notes: z.string().nullable(),
-		favorite: z.boolean(),
+		notes: OmittableTextSchema,
+		favorite: z.boolean().optional(),
 		fields: z
 			.array(
 				z.object({
@@ -92,12 +123,13 @@ export const BwItemSchema = z
 					type: z.number(),
 				}),
 			)
-			.nullable(),
+			.nullable()
+			.optional(),
 		login: z
 			.object({
-				username: z.string().nullable(),
-				password: z.string().nullable(),
-				totp: z.string().nullable(),
+				username: OmittableTextSchema,
+				password: OmittableTextSchema,
+				totp: OmittableTextSchema,
 				uris: z
 					.array(
 						z.object({
@@ -105,8 +137,23 @@ export const BwItemSchema = z
 							uri: z.string(),
 						}),
 					)
-					.nullable(),
+					.nullable()
+					.optional(),
+			})
+			.passthrough()
+			.nullable()
+			.optional(),
+		card: z
+			.object({
+				cardholderName: OmittableTextSchema,
+				brand: OmittableTextSchema,
+				number: OmittableTextSchema,
+				// Numeric in items written by hand or by an importer.
+				expMonth: z.union([z.string(), z.number()]).nullable().optional(),
+				expYear: z.union([z.string(), z.number()]).nullable().optional(),
+				code: OmittableTextSchema,
 			})
+			.passthrough()
 			.nullable()
 			.optional(),
 		reprompt: z.number().optional(),

package/src/cli/commands/get.ts

@@ -1,31 +1,47 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitData, emitLog } from "../io.ts";
-import { readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { emitData, emitLog, emitRaw } from "../io.ts";
+import { BUILTIN_FIELDS, readItemField, readTotp, readTotpSecret } from "../../bw/fields.ts";
+import { CARD_FIELDS } from "../../bw/cards.ts";
 import { CliError, ExitCode } from "../errors.ts";
 import type { GlobalOptions } from "../types.ts";
 
 /** Seconds left below which `--fresh` waits, when the flag is given bare. */
 const DEFAULT_FRESH_SECONDS = 5;
 
+/** Written once so `get` and `field` describe `--raw` in the same words. */
+const RAW_DESCRIPTION =
+	"Suppress only the trailing newline bwx adds; newlines stored in the value are kept";
+
+interface GetOptions {
+	fresh?: string | boolean;
+	seed?: boolean;
+	raw?: boolean;
+}
+
 export function registerGet(program: Command): void {
 	program
 		.command("get")
 		.description("Get a field from a vault item (built-in or custom)")
-		.argument("<field>", "Field: password | username | totp | notes | uri | item | <custom>")
+		.argument(
+			"<field>",
+			`Field: ${BUILTIN_FIELDS.join(" | ")} | <custom>. Card items also take: ${CARD_FIELDS.join(" | ")}`,
+		)
 		.argument("<item>", "Item name or ID")
 		.option(
 			"--fresh [seconds]",
 			`Wait for the next TOTP window if fewer than N seconds remain (default ${DEFAULT_FRESH_SECONDS})`,
 		)
 		.option("--seed", "Emit the stored TOTP secret instead of a code")
+		.option("--raw", RAW_DESCRIPTION)
 		.action(async function (
 			this: Command,
 			field: string,
 			item: string,
-			localOpts: { fresh?: string | boolean; seed?: boolean },
+			localOpts: GetOptions,
 		) {
 			const opts = getGlobalOpts(this);
+			assertRawUsable(localOpts, opts);
 
 			if (field === "totp") {
 				await emitTotp(item, localOpts, opts);
@@ -34,9 +50,18 @@ export function registerGet(program: Command): void {
 
 			assertTotpOnlyFlags(field, localOpts);
 
-			const value = await readItemField(field, item, opts);
-			// `item` is the one field that is itself JSON — emit it as structure.
-			emitData(field === "item" ? JSON.parse(value) : value, opts);
+			const value = await readItemField(field, item, opts, {
+				verbatim: localOpts.raw,
+			});
+
+			// `item` is the one field that is itself JSON, so it is emitted as
+			// structure — except under `--raw`, which promised the bytes `bw` gave us.
+			if (field === "item" && !localOpts.raw) {
+				emitData(JSON.parse(value), opts);
+				return;
+			}
+
+			emitValue(value, localOpts, opts);
 		});
 
 	program
@@ -46,19 +71,57 @@ export function registerGet(program: Command): void {
 		// alongside it — the two used to take their arguments back to front.
 		.argument("<name>", "Custom field name")
 		.argument("<item>", "Item name or ID")
-		.action(async function (this: Command, name: string, item: string) {
+		.option("--raw", RAW_DESCRIPTION)
+		.action(async function (
+			this: Command,
+			name: string,
+			item: string,
+			localOpts: { raw?: boolean },
+		) {
 			const opts = getGlobalOpts(this);
+			assertRawUsable(localOpts, opts);
+
 			try {
-				emitData(
-					await readItemField(name, item, opts, { customOnly: true }),
-					opts,
-				);
+				const value = await readItemField(name, item, opts, { customOnly: true });
+				emitValue(value, localOpts, opts);
 			} catch (err) {
 				throw withOrderHint(err);
 			}
 		});
 }
 
+/**
+ * Emits one field value. `--raw` writes it alone, so piping a secret into a
+ * consumer that reads stdin literally does not append bwx's newline to it;
+ * `meta` describes the JSON envelope and so never applies on that path.
+ */
+function emitValue(
+	value: string,
+	localOpts: { raw?: boolean },
+	opts: GlobalOptions,
+	meta?: Record<string, unknown>,
+): void {
+	if (localOpts.raw) {
+		emitRaw(value);
+		return;
+	}
+	emitData(value, opts, meta);
+}
+
+/**
+ * `--json` is an envelope — the value arrives quoted, escaped, and wrapped in
+ * `{ "data": … }` — so its trailing newline is the least of what `--raw` would
+ * have to undo. Saying so beats silently letting one win.
+ */
+function assertRawUsable(localOpts: { raw?: boolean }, opts: GlobalOptions): void {
+	if (localOpts.raw && opts.json) {
+		throw new CliError(
+			"--raw and --json cannot be combined: --json wraps the value in an envelope. Use one or the other.",
+			ExitCode.BadArgs,
+		);
+	}
+}
+
 /**
  * Emits a TOTP alongside how long it stays valid. The remainder rides in the
  * `--json` envelope's `meta` rather than replacing `data`, so `data` is still
@@ -66,7 +129,7 @@ export function registerGet(program: Command): void {
  */
 async function emitTotp(
 	item: string,
-	localOpts: { fresh?: string | boolean; seed?: boolean },
+	localOpts: GetOptions,
 	opts: GlobalOptions,
 ): Promise<void> {
 	if (localOpts.seed) {
@@ -76,7 +139,7 @@ async function emitTotp(
 				ExitCode.BadArgs,
 			);
 		}
-		emitData(await readTotpSecret(item, opts), opts);
+		emitValue(await readTotpSecret(item, opts), localOpts, opts);
 		return;
 	}
 
@@ -87,7 +150,7 @@ async function emitTotp(
 	});
 
 	emitLog(`Valid for ${totp.secondsRemaining}s`, opts);
-	emitData(totp.code, opts, {
+	emitValue(totp.code, localOpts, opts, {
 		secondsRemaining: totp.secondsRemaining,
 		period: totp.period,
 	});
@@ -115,10 +178,7 @@ function parseFreshSeconds(raw: string | boolean | undefined): number | undefine
  * Accepting `--fresh` on a password would read as "give me a fresh password",
  * which is not what it does. Rejecting it beats quietly ignoring it.
  */
-function assertTotpOnlyFlags(
-	field: string,
-	localOpts: { fresh?: string | boolean; seed?: boolean },
-): void {
+function assertTotpOnlyFlags(field: string, localOpts: GetOptions): void {
 	const used = [
 		localOpts.fresh !== undefined ? "--fresh" : null,
 		localOpts.seed ? "--seed" : null,

package/src/cli/commands/run.ts

@@ -70,7 +70,8 @@ export function parseEnvSpecs(raws: string[]): EnvSpec[] {
 /**
  * Splits `NAME=<field>:<item>` on the first `=` and then the first `:`, so item
  * names may contain colons (`password:http://my.router`) while field names may not.
- * Fields resolve exactly as in `bwx get`: built-ins first, otherwise custom fields.
+ * Fields resolve exactly as in `bwx get`: built-ins first, then card fields on a card
+ * item, otherwise custom fields.
  */
 export function parseEnvSpec(raw: string): EnvSpec {
 	const eq = raw.indexOf("=");

package/src/cli/io.ts

@@ -34,6 +34,16 @@ export function emitData(
 	}
 }
 
+/**
+ * Writes a value and nothing else — no newline, no formatting. {@link emitData}'s
+ * newline is a courtesy to terminals, but a consumer that reads stdin literally
+ * takes it as the last byte of the secret. Newlines *inside* the value are the
+ * value's own and are left alone.
+ */
+export function emitRaw(value: string): void {
+	process.stdout.write(value);
+}
+
 export function emitLog(message: string, opts: GlobalOptions): void {
 	if (opts.quiet || opts.json) return;
 	process.stderr.write(message + "\n");