bwx 0.4.0 → 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.0",
+  "version": "0.5.0",
   "type": "module",
   "keywords": [
     "bitwarden",
@@ -12,7 +12,8 @@
   ],
   "files": [
     "bin",
-    "src"
+    "src",
+    "skill"
   ],
   "bin": {
     "bwx": "bin/bwx"

package/skill/bwx/SKILL.md

@@ -0,0 +1,196 @@
+---
+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.
+---
+
+# bwx
+
+Extended Bitwarden CLI. Wraps `bw` with auto-unlock, session caching, and structured output.
+
+## Quick start
+
+```bash
+bwx get password "GitHub"               # retrieve a password (auto-unlocks)
+bwx get totp "AWS (user@example.com)"   # TOTP code
+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 "API Key" "Acme"                # custom field by name
+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
+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/
+
+bwx create --name "API Key" --notes "sk_live_abc123" --field account=acme
+printf '%s' "$TOKEN" | bwx create --type login --name "GitHub" --username user --password-stdin --uri https://github.com
+bwx create --name "Acme" --field-file '!API Key=./token.txt' --field-env account=ACME_ACCOUNT
+echo "secret" | bwx create --name "Piped Note"
+```
+
+## Commands
+
+### `bwx get <field> <item>`
+
+Built-in fields: `password | username | totp | notes | uri | item`.
+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
+suggestions instead of retrying variations — the answer is usually in them.
+
+### `bwx field <name> <item>`
+
+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`, `--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.
+This is the preferred way to give a subprocess a credential.
+
+```bash
+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).
+- 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).
+- `-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>`
+
+Lists attachments for an item. Aliases: `bwx attachment`, `bwx attachments`; `list` has `ls`.
+
+### `bwx attach get <item> <attachment>`
+
+Downloads an attachment by ID or filename. Defaults to saving as the attachment filename in the current directory. Use `--output <path>` to choose a file or directory.
+
+### `bwx create [options]`
+
+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.
+
+### `bwx edit <item> [options]`
+
+Fetch → patch → push.
+```bash
+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`, `--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" --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 + 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 |
+|------|--------|
+| `--json` | `{ "data": ... }` on success, `{ "error": { "message", "exitCode" } }` on failure |
+| `--plain` | Stable parseable lines on stdout |
+| `-q` | Suppress logs and warnings |
+| `-v` | Verbose (stack traces on error) |
+| `--timeout <duration>` | Deadline per `bw` call (default `1m`, `0` disables) → exit 8 |
+| `--sync-if-older-than <duration>` | Sync first when the vault last synced longer ago |
+
+Durations: `250ms`, `30s`, `15m`, `2h`, `1d`; a bare number is seconds.
+
+## Vault freshness
+
+Reads come from the local vault copy. Reads warn on stderr when the last sync is over 24h
+old — a rotated secret can otherwise look valid or missing. Pass
+`--sync-if-older-than 15m` to sync first instead, or run `bwx sync`. Warnings reach stderr
+even under `--json`; `-q` silences them.
+
+## Safety rules
+
+- 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`.
+- Never echo, log, checksum, or commit retrieved values; `unset` temporary variables.
+
+## Auth
+
+- Master password: macOS Keychain (account `bitwarden`, service `bitwarden-master`)
+- Session cached to `~/.config/bwx/session` (mode 600), given to `bw` via `BW_SESSION`
+- Freshness snapshot cached to `~/.config/bwx/state.json`

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;
 }