bwx 0.7.0 → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vladislav Forsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -69,10 +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 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`) |
+| `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 |
@@ -104,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`
@@ -360,3 +383,7 @@ Breaking changes, all of them cases where the old behavior failed quietly:
 ## Stack
 
 Bun, TypeScript, Commander, Zod, picocolors.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,15 +1,34 @@
 {
   "name": "bwx",
-  "version": "0.7.0",
-  "type": "module",
+  "version": "0.8.1",
+  "description": "Extended Bitwarden CLI for scripts and agents — auto-unlock via macOS Keychain, session caching, local TOTP, structured output",
   "keywords": [
     "bitwarden",
+    "bitwarden-cli",
     "cli",
     "vault",
     "secrets",
+    "secrets-management",
+    "totp",
+    "keychain",
+    "macos",
     "ai-agents",
     "bun"
   ],
+  "license": "MIT",
+  "author": "Vladislav Forsh <vforsh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vforsh/bwx.git"
+  },
+  "homepage": "https://github.com/vforsh/bwx#readme",
+  "bugs": {
+    "url": "https://github.com/vforsh/bwx/issues"
+  },
+  "type": "module",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "files": [
     "bin",
     "src",

package/skill/bwx/SKILL.md

@@ -20,6 +20,7 @@ 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
@@ -78,6 +79,22 @@ 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

package/src/bw/fields.ts

@@ -40,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;
 }
 
 /**
@@ -81,7 +89,7 @@ export async function readItemField(
 		}
 
 		return isBuiltinField(field)
-			? readBuiltinField(field, item, opts)
+			? readBuiltinField(field, item, opts, options?.verbatim)
 			: readCustomField(field, item, opts);
 	});
 }
@@ -330,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) {

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/cli/commands/get.ts

@@ -1,6 +1,6 @@
 import type { Command } from "commander";
 import { getGlobalOpts } from "../program.ts";
-import { emitData, emitLog } from "../io.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";
@@ -9,6 +9,16 @@ 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")
@@ -23,13 +33,15 @@ export function registerGet(program: Command): void {
 			`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);
@@ -38,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
@@ -50,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
@@ -70,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) {
@@ -80,7 +139,7 @@ async function emitTotp(
 				ExitCode.BadArgs,
 			);
 		}
-		emitData(await readTotpSecret(item, opts), opts);
+		emitValue(await readTotpSecret(item, opts), localOpts, opts);
 		return;
 	}
 
@@ -91,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,
 	});
@@ -119,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/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");