bwx 0.4.1 → 0.5.0

package/README.md

@@ -54,20 +54,27 @@ bwx doctor
 
 | Command | Description |
 |---------|-------------|
-| `bwx status` | Show vault state |
+| `bwx status` | Show vault state and whether reads work right now |
 | `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) |
 
+`status` reports a `session` alongside the vault state, because `bw` answers for the
+vault and not for bwx: a `locked` vault with a `valid` session reads fine and needs no
+unlock. `valid` means reads work now, `stale` means the cached session was rejected, and
+`none` means the next read unlocks.
+
 ### Read
 
 | Command | Description |
 |---------|-------------|
 | `bwx get <field> <item>` | Get field (`password`, `username`, `totp`, `notes`, `uri`, `item`) |
-| `bwx field <item> <name>` | Get custom field by name |
+| `bwx field <name> <item>` | Get custom field by name (same argument order as `get`) |
 | `bwx search <query>` | Search items (`--type`, `--folder`, `--limit`, `--full-items`) |
-| `bwx list [type]` | List items (`--folder`, `--limit`, `--full-items`) |
+| `bwx list [type]` | List items (`--type`, `--folder`, `--limit`, `--full-items`) |
+| `bwx folders` | List folder names and IDs |
+| `bwx trash` | List items in the trash |
 | `bwx run --env NAME=<field>:<item> -- <cmd>` | Run a command with secrets in its environment |
 | `bwx attach list <item>` | List attachments for an item |
 | `bwx attach get <item> <attachment>` | Download attachment by ID or filename |
@@ -77,6 +84,41 @@ human, `--plain`, and `--json` form, so asking for machine-readable output never
 what is exposed. `--full-items` is the explicit opt-in to complete item objects, which
 carry passwords, notes, and custom fields.
 
+A lookup that finds nothing suggests what you probably meant, and one that matches
+several items lists them, so neither ends in a guessing round:
+
+```
+$ bwx get password "GitHub PAT vforsh old"
+error: No item matching "GitHub PAT vforsh old". Did you mean:
+
+  934c1f57-…  note  GitHub PAT (vforsh)
+  3683fb9a-…  note  GitHub PAT (yaforsh) [codex-monitor-pr]
+```
+
+### Listings are capped
+
+Listings stop at 50 items by default — an uncapped `bwx list` returns the whole vault,
+and with `--full-items` that is every secret in one call. `--limit 0` opts out. Truncation
+is never silent: it warns on stderr (surviving `--json`) and adds `meta` to the JSON
+envelope.
+
+```bash
+bwx list --limit 0            # everything
+bwx list --json               # { "data": [...], "meta": { "total": 491, "shown": 50, "truncated": true } }
+```
+
+### Folders
+
+`--folder` takes a name or an ID on `list`, `search`, `create`, and `edit`; `none` means
+the unfiled bucket. Names are resolved against the vault, so `bwx folders` is only needed
+to see what exists.
+
+```bash
+bwx folders
+bwx list --folder "API Keys"
+bwx edit "Acme" --folder none     # unfile
+```
+
 ### Secrets into a child process
 
 `bwx run` resolves secrets and places them only in the child's environment: nothing is
@@ -114,6 +156,34 @@ The check is cached in `~/.config/bwx/state.json`, so a fresh vault costs no ext
 | `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`) |
+| `bwx restore <item>` | Restore an item from the trash |
+| `bwx generate` | Generate a password or passphrase (local, no vault access) |
+
+Login-only flags (`--username`, any `--password-*`, `--uri`) require a login item. A
+secure note has nowhere to put them, so passing them to one is an error rather than an
+exit 0 over a credential that was silently dropped.
+
+`bwx delete` requires `--force` whenever it is not talking to a terminal. The confirmation
+prompt cannot render for a script or an agent, so without it `--force` would be decorative
+and every non-interactive delete unguarded. Deletes go to the trash unless `--permanent`,
+and `bwx trash` / `bwx restore` are the way back.
+
+### Generated passwords
+
+`--password-generate` on `create` and `edit` sends a new secret straight to the vault. It
+is never printed, never echoed back in `--json`, and never reaches a terminal, a
+transcript, or a log — which is what makes it safe to use from an agent.
+
+```bash
+bwx create --type login --name "Deploy" --username svc --password-generate
+bwx edit "Deploy" --password-generate --generate-length 32
+bwx generate --length 32                  # print one instead
+bwx generate --passphrase --words 5
+```
+
+`bwx generate` runs locally and needs no unlocked vault. Flags: `--length <n>`,
+`--no-uppercase`, `--no-lowercase`, `--no-numbers`, `-s/--special`, `--ambiguous`,
+`--passphrase`, `--words <n>`, `--separator <char>`, `--capitalize`, `--include-number`.
 
 ### Config
 
@@ -156,7 +226,7 @@ Supported source flags:
 
 | Flag | Effect |
 |------|--------|
-| `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }` |
+| `--json` | JSON output: `{ "data": ... }` / `{ "error": ... }`, plus `meta` where a response describes itself |
 | `--plain` | Tab-separated, one item per line |
 | `-q, --quiet` | Suppress logs and warnings |
 | `-v, --verbose` | Include stack traces |
@@ -191,6 +261,17 @@ Field syntax for `--field`, `--field-file`, `--field-env`, and edit variants:
 | 8 | Timeout |
 | 9 | User cancelled |
 
+## Upgrading to 0.5.0
+
+Breaking changes, all of them cases where the old behavior failed quietly:
+
+- `bwx field` takes `<name> <item>`, matching `bwx get`. It was `<item> <name>`.
+- `bwx delete` needs `--force` when not interactive; it used to delete unprompted.
+- `bwx list` and `bwx search` stop at 50 items unless given `--limit`. Pass `--limit 0`
+  for the old behavior.
+- `--limit` rejects non-numeric values instead of ignoring them (and returning everything).
+- Login-only flags on a secure note are an error instead of a silent drop.
+
 ## Stack
 
 Bun, TypeScript, Commander, Zod, picocolors.

package/package.json

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

package/skill/bwx/SKILL.md

@@ -17,7 +17,7 @@ bwx get notes "Deploy key"              # secure note content
 bwx get uri "GitHub"                    # first URI
 bwx get item "GitHub"                   # full item JSON
 bwx get "API Key" "Acme"                # custom field by name
-bwx field "Acme" "API Key"              # custom field alias
+bwx field "API Key" "Acme"              # custom-field-only lookup, same arg order
 
 bwx search github                       # fuzzy search, human table
 bwx search github --json                # id/type/name/username only — no secrets
@@ -26,6 +26,9 @@ bwx search github --type login --limit 5
 # hand a secret to a child process instead of printing it
 bwx run --env KEENETIC_PASS=password:'http://my.keenetic.net' -- expect ./recovery.exp
 
+# generate straight into the vault — the value never enters your context
+bwx create --type login --name "Deploy" --username svc --password-generate
+
 bwx attach list "Apple Developer"       # list item attachments
 bwx attach get "Apple Developer" AuthKey.p8
 bwx attach get "Apple Developer" AuthKey.p8 --output ./secrets/
@@ -43,18 +46,31 @@ echo "secret" | bwx create --name "Piped Note"
 Built-in fields: `password | username | totp | notes | uri | item`.
 Anything else is looked up as a custom field. Lists available fields on miss.
 
-### `bwx field <item> <name>`
+A miss suggests near matches; an ambiguous name lists candidates with IDs. Read the
+suggestions instead of retrying variations — the answer is usually in them.
+
+### `bwx field <name> <item>`
 
-Alias for retrieving custom fields with item-first argument order.
+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).
 
 ### `bwx search <query>` / `bwx list [type]`
 
-Flags: `--type login|note|card|identity` (`search`), `--folder <id>`, `--limit <n>`, `--full-items`
+Flags: `--type login|note|card|identity`, `--folder <name|id>`, `--limit <n>`, `--full-items`
 
 Human, `--plain`, and `--json` output all carry the same reduced projection — `id`, `type`,
 `name`, `username` — so listings never leak passwords, notes, or custom fields. `--full-items`
 opts into complete item objects and **does** include secrets; avoid it in logged sessions.
 
+**Listings stop at 50 items** unless you pass `--limit` (`--limit 0` for all). Truncation is
+reported on stderr and in `meta` on the JSON envelope — check it before concluding a listing
+was complete. `--limit` rejects non-numeric values rather than ignoring them.
+
+### `bwx folders`
+
+Lists folder names and IDs. `--folder` accepts either on `list`, `search`, `create`, and
+`edit`; `none` selects unfiled items.
+
 ### `bwx run --env NAME=<field>:<item> -- <command>`
 
 Resolves secrets and injects them into the child's environment only — not stdout, not argv.
@@ -70,6 +86,8 @@ bwx run --env TOKEN='API Key:Acme' --env USER=username:Acme -- ./deploy.sh
 - 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).
 - `-v` logs injected variable names only, never values.
+- Several variables from one item cost a single vault read, so group them here rather
+  than issuing separate `bwx get` calls.
 
 ### `bwx attach list <item>`
 
@@ -81,7 +99,10 @@ Downloads an attachment by ID or filename. Defaults to saving as the attachment
 
 ### `bwx create [options]`
 
-Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder`, `--favorite`, `--from-json`
+Flags: `--type login|note`, `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--uri` (repeatable), `--field k=v` (repeatable), `--field-file k=path`, `--field-env k=ENV`, `--folder <name|id>`, `--favorite`, `--from-json`
+
+`--username`, any `--password-*`, and `--uri` require `--type login`; a note cannot hold
+them and passing them to one is now an error rather than a silent drop.
 
 Field syntax: `k=v` (text), `!k=v` (hidden), `bool:k=v` (boolean). The same key syntax works for `--field-file` and `--field-env`, where the value is a path or environment variable name. Stdin is read as `--notes` when piped; prefer `--password-stdin` for login passwords.
 
@@ -93,26 +114,51 @@ bwx edit "API Key" --add-field region=us-east-1
 printf '%s' "$TOKEN" | bwx edit "GitHub" --password-stdin --uri https://github.com
 bwx edit "Note" --rm-field old-key
 ```
-Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder`, `--favorite/--no-favorite`, `--from-json`
+Flags: `--name`, `--notes`, `--notes-file`, `--username`, `--password`, `--password-stdin`, `--password-file`, `--password-env`, `--password-generate`, `--generate-length <n>`, `--uri` (replaces all), `--add-field k=v`, `--add-field-file k=path`, `--add-field-env k=ENV`, `--rm-field name`, `--folder <name|id>` (`none` unfiles), `--favorite/--no-favorite`, `--from-json`
 
 ### `bwx delete <item>`
 
 ```bash
-bwx delete "Test Note"              # prompts in TTY
-bwx delete "Test Note" --force      # skip prompt
-bwx delete "Test Note" --permanent  # no trash
+bwx delete "Test Note" --force      # --force is REQUIRED when not a TTY
+bwx delete "Test Note" --permanent --force  # skip the trash
+bwx trash                           # what is recoverable
+bwx restore "Test Note"             # undo a non-permanent delete
+```
+
+The prompt only exists for a human at a terminal, so an agent must pass `--force`
+deliberately. Deletes are recoverable through `bwx restore` unless `--permanent`.
+
+### `bwx generate`
+
+```bash
+bwx generate --length 32
+bwx generate --passphrase --words 5 --separator -
 ```
 
+Local, no vault access, no unlock. Flags: `--length <n>`, `--no-uppercase`,
+`--no-lowercase`, `--no-numbers`, `-s/--special`, `--ambiguous`, `--passphrase`,
+`--words <n>`, `--separator <char>`, `--capitalize`, `--include-number`.
+
+Prefer `--password-generate` on `create`/`edit` over generating and passing the value:
+it goes to the vault without ever entering your context, and `--json` returns
+`***GENERATED***` in place of the password.
+
 ### Other
 
 | Command | Description |
 |---------|-------------|
-| `bwx status` | Vault state (no auto-unlock) |
+| `bwx status` | Vault state + session usability (no auto-unlock) |
 | `bwx sync` | Force vault sync |
 | `bwx unlock` / `bwx lock` | Manual session control |
+| `bwx folders` | Folder names and IDs |
+| `bwx trash` / `bwx restore <item>` | Inspect and undo deletes |
 | `bwx config list` / `bwx cfg ls` | Show config path + redacted content |
 | `bwx config master-password` | Set/update master password in Keychain |
 
+`bwx status` reports `session: valid | stale | none` separately from the vault state.
+**A `locked` vault with a `valid` session reads fine — do not run `bwx unlock` on it.**
+Only `stale`/`none` mean the next read pays for an unlock.
+
 ## Global flags
 
 | Flag | Effect |
@@ -137,6 +183,7 @@ even under `--json`; `-q` silences them.
 
 - Never use `--full-items` (or `get item` for discovery) in logged sessions.
 - Prefer `bwx run --env ...` over `export VAR="$(bwx get ...)"`; secrets never touch stdout or argv.
+- Prefer `--password-generate` over generating a secret yourself and passing it in.
 - Request the narrowest field, resolving an exact item ID first.
 - Use `-q` for command substitution so unlock logs cannot contaminate merged output.
 - On writes, prefer `--password-stdin`, `--password-env`, `--field-file`, `--field-env`.

package/src/bw/encoding.ts

@@ -98,7 +98,8 @@ export interface PatchOptions {
 	uris?: string[];
 	addFields?: ParsedField[];
 	rmFields?: string[];
-	folderId?: string;
+	/** `null` unfiles the item; `undefined` leaves its folder alone. */
+	folderId?: string | null;
 	favorite?: boolean;
 }
 

package/src/bw/fields.ts

@@ -4,7 +4,7 @@ import type { GlobalOptions } from "../cli/types.ts";
 import { summarizeItem, type ItemSummary } from "./items.ts";
 import { runBwOrThrow } from "./runner.ts";
 import { withSession } from "./session.ts";
-import { BwItemSchema } from "./types.ts";
+import { BwItemSchema, type BwItem } from "./types.ts";
 
 /** Fields `bw get` resolves natively; anything else is a custom field name. */
 const BUILTIN_FIELDS = [
@@ -16,6 +16,12 @@ const BUILTIN_FIELDS = [
 	"item",
 ] as const;
 
+/**
+ * `totp` is a computed code, not stored data — only `bw get totp` can derive it,
+ * so it is the one field that cannot be served from a fetched item.
+ */
+const DERIVED_FIELDS = new Set(["totp"]);
+
 function isBuiltinField(field: string): boolean {
 	return (BUILTIN_FIELDS as readonly string[]).includes(field);
 }
@@ -28,10 +34,23 @@ export interface ReadFieldOptions {
 	customOnly?: boolean;
 }
 
+/**
+ * Raised when the item was found but the requested field was not. Distinct from
+ * a missing *item* so the "did you mean this item?" suggestions below never fire
+ * on an error that already names the fields that do exist.
+ */
+class FieldMissingError extends CliError {}
+
+/** One `(field, item)` pair to resolve — see {@link readFields}. */
+export interface FieldRequest {
+	field: string;
+	item: string;
+	options?: ReadFieldOptions;
+}
+
 /**
  * Reads one field from a vault item and returns it verbatim (`item` yields the
  * item JSON), leaving the caller to decide whether the value is printed at all.
- * Ambiguous item lookups fail with the candidate list instead of a raw bw error.
  */
 export async function readItemField(
 	field: string,
@@ -39,22 +58,132 @@ export async function readItemField(
 	opts: GlobalOptions,
 	options?: ReadFieldOptions,
 ): Promise<string> {
+	return withLookupHelp(item, opts, () =>
+		isBuiltinField(field) && !options?.customOnly
+			? readBuiltinField(field, item, opts)
+			: readCustomField(field, item, opts),
+	);
+}
+
+/**
+ * Resolves many fields at once, paying a single `bw get item` per distinct item
+ * rather than one `bw` spawn per field. Each spawn costs ~2.5s, so a caller
+ * pulling a username and password from one item halves its own runtime.
+ *
+ * Returns values positionally aligned with `requests`.
+ */
+export async function readFields(
+	requests: FieldRequest[],
+	opts: GlobalOptions,
+): Promise<string[]> {
+	const values = new Array<string>(requests.length);
+	const byItem = new Map<string, number[]>();
+
+	for (const [index, request] of requests.entries()) {
+		const bucket = byItem.get(request.item);
+		if (bucket) bucket.push(index);
+		else byItem.set(request.item, [index]);
+	}
+
+	for (const [item, indexes] of byItem) {
+		// A single `bw` process at a time: each read may trigger an unlock, and
+		// concurrent unlocks would race over the cached session.
+		const derived = indexes.filter((i) => isDerived(requests[i]!));
+		const stored = indexes.filter((i) => !isDerived(requests[i]!));
+
+		if (stored.length > 0) {
+			const fetched = await withLookupHelp(item, opts, () =>
+				fetchItem(item, opts),
+			);
+			for (const index of stored) {
+				const request = requests[index]!;
+				values[index] = extractField(fetched, request.field, request.options);
+			}
+		}
+
+		for (const index of derived) {
+			const request = requests[index]!;
+			values[index] = await withLookupHelp(item, opts, () =>
+				readBuiltinField(request.field, item, opts),
+			);
+		}
+	}
+
+	return values;
+}
+
+function isDerived(request: FieldRequest): boolean {
+	return !request.options?.customOnly && DERIVED_FIELDS.has(request.field);
+}
+
+/**
+ * Turns bw's bare "Not found." and "More than one result" into errors that name
+ * the candidates, so a caller can correct itself without a round of guessing.
+ */
+async function withLookupHelp<T>(
+	item: string,
+	opts: GlobalOptions,
+	fn: () => Promise<T>,
+): Promise<T> {
 	try {
-		return isBuiltinField(field) && !options?.customOnly
-			? await readBuiltinField(field, item, opts)
-			: await readCustomField(field, item, opts);
+		return await fn();
 	} catch (err) {
+		if (err instanceof FieldMissingError) throw err;
+
 		if (err instanceof CliError && /more than one result/i.test(err.message)) {
-			const matches = await findMatches(item);
 			throw new CliError(
-				formatAmbiguousError(item, matches, opts),
+				formatAmbiguous(item, await findMatches(item), opts),
 				ExitCode.BadArgs,
 			);
 		}
+
+		if (err instanceof CliError && err.exitCode === ExitCode.NotFound) {
+			throw new CliError(
+				formatNotFound(item, await findSimilar(item), opts),
+				ExitCode.NotFound,
+			);
+		}
+
 		throw err;
 	}
 }
 
+async function fetchItem(item: string, opts: GlobalOptions): Promise<BwItem> {
+	const json = await withSession(opts, () => runBwOrThrow(["get", "item", item]));
+	return BwItemSchema.parse(JSON.parse(json));
+}
+
+/** Mirrors what `bw get <field>` would have returned for an already-fetched item. */
+function extractField(
+	item: BwItem,
+	field: string,
+	options?: ReadFieldOptions,
+): string {
+	if (!isBuiltinField(field) || options?.customOnly) {
+		return pickCustomField(item, field);
+	}
+
+	if (field === "item") return JSON.stringify(item);
+
+	const value =
+		field === "notes"
+			? item.notes
+			: field === "uri"
+				? (item.login?.uris?.[0]?.uri ?? null)
+				: field === "username"
+					? (item.login?.username ?? null)
+					: (item.login?.password ?? null);
+
+	if (!value) {
+		throw new FieldMissingError(
+			`No ${field} found for item: ${item.name}`,
+			ExitCode.NotFound,
+		);
+	}
+
+	return value;
+}
+
 async function readBuiltinField(
 	field: string,
 	item: string,
@@ -65,7 +194,7 @@ async function readBuiltinField(
 	);
 
 	if (!result) {
-		throw new CliError(
+		throw new FieldMissingError(
 			`No ${field} found for item: ${item}`,
 			ExitCode.NotFound,
 		);
@@ -79,20 +208,21 @@ async function readCustomField(
 	item: string,
 	opts: GlobalOptions,
 ): Promise<string> {
-	const json = await withSession(opts, () =>
-		runBwOrThrow(["get", "item", item]),
-	);
+	return pickCustomField(await fetchItem(item, opts), fieldName);
+}
 
-	const parsed = BwItemSchema.parse(JSON.parse(json));
-	const fields = parsed.fields ?? [];
+function pickCustomField(item: BwItem, fieldName: 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 msg = available
-			? `Field "${fieldName}" not found. Available: ${available}`
-			: `Field "${fieldName}" not found (item has no custom fields)`;
-		throw new CliError(msg, ExitCode.NotFound);
+		throw new FieldMissingError(
+			available
+				? `Field "${fieldName}" not found. Available: ${available}`
+				: `Field "${fieldName}" not found (item has no custom fields)`,
+			ExitCode.NotFound,
+		);
 	}
 
 	return match.value ?? "";
@@ -108,7 +238,95 @@ async function findMatches(query: string): Promise<ItemSummary[]> {
 	}
 }
 
-function formatAmbiguousError(
+/**
+ * Looks for what the caller probably meant. bw's own search already came back
+ * empty, so this pulls the item list once and scores it locally: one `bw` spawn
+ * on the error path, and matching that survives typos and extra words the way
+ * repeated `--search` calls do not.
+ */
+async function findSimilar(query: string): Promise<ItemSummary[]> {
+	let summaries: ItemSummary[];
+	try {
+		const json = await runBwOrThrow(["list", "items"]);
+		const items: Array<Record<string, unknown>> = JSON.parse(json);
+		summaries = items.map(summarizeItem);
+	} catch {
+		return [];
+	}
+
+	return rankSimilar(query, summaries);
+}
+
+/** Pure so the suggestion quality is testable without a vault. */
+export function rankSimilar(
+	query: string,
+	items: ItemSummary[],
+	max = MAX_SUGGESTIONS,
+): ItemSummary[] {
+	const tokens = tokenize(query);
+	if (tokens.length === 0) return [];
+
+	const scored = items
+		.map((item) => ({ item, score: scoreMatch(tokens, item) }))
+		.filter((entry) => entry.score > 0)
+		.sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name));
+
+	return scored.slice(0, max).map((entry) => entry.item);
+}
+
+/**
+ * Length gates on the fuzzier rules keep short words from matching by accident —
+ * without them "not" pulls in every item containing "evernote", and a suggestion
+ * list full of noise is worse than none.
+ */
+function scoreMatch(tokens: string[], item: ItemSummary): number {
+	const haystack = `${item.name} ${item.username ?? ""}`.toLowerCase();
+	const itemTokens = tokenize(haystack);
+
+	let score = 0;
+	for (const token of tokens) {
+		if (itemTokens.includes(token)) score += 3;
+		else if (token.length >= 4 && haystack.includes(token)) score += 2;
+		else if (
+			token.length >= 3 &&
+			itemTokens.some((other) => other.startsWith(token))
+		) {
+			score += 1;
+		}
+	}
+
+	return score;
+}
+
+function tokenize(value: string): string[] {
+	return value
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter((token) => token.length >= 2);
+}
+
+const MAX_SUGGESTIONS = 5;
+
+function formatNotFound(
+	query: string,
+	matches: ItemSummary[],
+	opts: GlobalOptions,
+): string {
+	if (matches.length === 0) {
+		return `No item matching "${query}". Run 'bwx search <query>' to find it.`;
+	}
+
+	if (opts.json) {
+		return `No item matching "${query}". Did you mean: ${JSON.stringify(matches)}`;
+	}
+
+	return [
+		`No item matching "${query}". Did you mean:\n`,
+		...matches.map(formatCandidate),
+	].join("\n");
+}
+
+function formatAmbiguous(
 	query: string,
 	matches: ItemSummary[],
 	opts: GlobalOptions,
@@ -121,13 +339,14 @@ function formatAmbiguousError(
 		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");
+	return [
+		`Multiple items match "${query}":\n`,
+		...matches.map(formatCandidate),
+		`\nUse a specific ID: ${pc.dim("bwx get <field> <id>")}`,
+	].join("\n");
+}
+
+function formatCandidate(match: ItemSummary): string {
+	const user = match.username ? ` (${match.username})` : "";
+	return `  ${pc.dim(match.id)}  ${pc.cyan(match.type)}  ${match.name}${pc.dim(user)}`;
 }