mnemonad-cli 0.1.1 → 0.3.0

package/README.md

@@ -15,16 +15,30 @@ signer's own wallet key.
 ### From npm (recommended)
 
 ```bash
-npm install -g mnemonad-cli
+npm install -g mnemonad-cli@latest
 mnemonad --help
 ```
 
-To pick up a new release later:
+To pick up a new release later, prefer reinstalling `@latest` over `npm update -g` — `update`
+has known quirks where it doesn't reliably bump an already-installed global package even when
+a newer version is published:
 
 ```bash
-npm update -g mnemonad-cli
+npm install -g mnemonad-cli@latest
+mnemonad --help    # banner shows the version — confirm it actually moved
 ```
 
+If it still reports the old version, you likely have two installs shadowing each other on
+`PATH` (common with nvm, after switching Node versions):
+
+```bash
+which mnemonad
+npm ls -g mnemonad-cli
+```
+
+If `which mnemonad` doesn't resolve into the `npm root -g` you just installed into, remove
+the stale one — `npm uninstall -g mnemonad-cli`, then reinstall.
+
 ### From this repo (for development)
 
 This package lives in the monorepo alongside `mnemonad` and `monadsync`, linked through a
@@ -62,15 +76,24 @@ mnemonad info [stream-id] [path] [options]     Show chain/wallet info, or full s
 mnemonad diff <stream-id> <path> [options]     List files added/modified/deleted locally vs the on-chain version
 mnemonad watch <stream-id> <path> [options]    Watch folder: auto-push on changes, auto-pull on remote updates
 mnemonad compact <stream-id> <path> [options]  Truncate old history and push folder as a fresh snapshot
+mnemonad burn <stream-id> --yes [options]      Permanently destroy a stream — irreversible
+mnemonad index <path> [options]                Build/update a local vector-search index (optional)
+mnemonad search <path> <query> [options]       Search a folder's vector index
 ```
 
 `<path>` is always required for any command that touches a folder — there is no need to
 `cd` into the folder first, but there's also no falling back to the current working
 directory: an omitted or mistyped path fails fast with an error rather than silently
-operating on wherever the CLI happened to be run from. The only command that can run with
-no path at all is `mnemonad info` with no stream id either (it just checks your configured
-chain/wallet). A stream id is recognized as a bare decimal number (`123`) or a
-`0x`-prefixed hex string; anything else in that position is treated as a path.
+operating on wherever the CLI happened to be run from. The commands that can run with no
+path at all are `mnemonad info` with no stream id either (it just checks your configured
+chain/wallet) and `mnemonad burn`, which never takes one. A stream id is recognized as a
+bare decimal number (`123`), a
+`0x`-prefixed hex string, or the network-qualified form the
+[explorer dApp](https://mnemonad.vercel.app)'s own URLs use —
+`testnet-0x648f18…` — pasted straight out of a `/stream/<id>` link. That form also sets
+`--chain` to match; pass `--chain` too only if it agrees, or the command refuses rather than
+guess which one you meant. Every command's own output always prints the bare id in hex
+(`0x` + the full 32-byte token id), matching the explorer's own display.
 
 Every command prints the installed CLI version as its first line of output.
 
@@ -81,9 +104,11 @@ Every command prints the installed CLI version as its first line of output.
 | `--chain <name>` | Chain: `testnet`, `mainnet`, `local` (default: `testnet`) |
 | `--rpc-url <url>` | Override the resolved RPC endpoint (e.g. a local Hardhat node) |
 | `--contract-address <addr>` | Registry address to use instead of the chain's known deployment (required with `--chain local`) |
-| `--gateway-url <url>` | IPFS gateway for reading externally-offloaded items (default: `https://gateway.pinata.cloud/ipfs/`, or `MNEMONAD_IPFS_GATEWAY` env var) |
+| `--gateway-url <url>` | IPFS gateway for reading externally-offloaded items (default: this project's Pinata dedicated gateway, or `MNEMONAD_IPFS_GATEWAY` env var) |
 | `--key <privkey>` | Monad private key (or set `MNEMONAD_KEY` env var) |
 | `--phrase <mnemonic>` | Mnemonic phrase instead of a raw key |
+| `--passkey` | Sign with a passkey instead: opens the explorer in your browser to sign in with WebAuthn, then relays signing requests to that tab for this command. Interactive only — not for scripts/CI. Cannot be combined with `--key`/`--phrase` |
+| `--auth-origin <url>` | Explorer deployment `--passkey` opens (default: this project's explorer deployment, or `MNEMONAD_AUTH_ORIGIN` env var) |
 | `--version <n>` | Version to restore or compare against (`pull`, `diff`, `info`; default: latest) |
 | `--exclude <p1,p2>` | Extra exclude patterns (comma-separated) |
 | `--no-compress` | Disable gzip compression |
@@ -91,12 +116,20 @@ Every command prints the installed CLI version as its first line of output.
 | `--encrypt-with <method>` | How to key it: `password` (needs `--password`), or `wallet` — the `--key`/`--phrase` account signs for it, and only that account can ever decrypt it. Implied by `--password` |
 | `--password <pw>` | Password to encrypt a new stream with, or decrypt an existing one |
 | `--pinata-jwt <jwt>` | Pinata JWT for IPFS offload of large files (or `PINATA_JWT` env var) |
-| `--manifest` | Write/use `.mnemonad` manifest for faster change detection |
+| `--manifest` | Write/use `.mnemonad` manifest for faster change detection. With no stream-id given, every command recovers it from an existing `.mnemonad` in the folder instead of requiring it explicitly |
 | `--force-snapshot` | Push a full snapshot regardless of prior history (repairs a corrupt stream) |
+| `--index` | `push`/`watch`: update the folder's search index before every push (takes `--db`/`--model`/`--chunk-size`/`--chunk-overlap`); if indexing fails, nothing is pushed |
 | `--poll-interval <s>` | `watch`: seconds between remote version checks (default: `2`) |
 | `--debounce <ms>` | `watch`: quiet period in ms before pushing after a local change (default: `1000`) |
 | `--push-only` | `watch`: disable auto-pull |
 | `--pull-only` | `watch`: disable auto-push |
+| `--yes` | Required by `burn` — explicit opt-in for an irreversible action, never assumed |
+| `--db <name>` | `index`/`search`: vector-index filename (default: `search_index.db`) |
+| `--model <name>` | `index` / `--index`: embedding model — `potion` (built in, the default for a new index) or `minilm` (needs `npm install -g mnemonad-search-transformers`), or a full model id. Without it, an existing index keeps its own model; `search` always uses the index's model |
+| `--rebuild` | `index` / `--index`: start the index over — the way to switch models (the next push uploads the whole index again) |
+| `--chunk-size <n>` | `index`: target characters per chunk (default: `1000`) |
+| `--chunk-overlap <n>` | `index`: characters of overlap between chunks (default: `150`) |
+| `--limit <n>`, `-k <n>` | `search`: number of results (default: `5`) |
 | `--help` | Show help |
 
 ### Authentication
@@ -117,6 +150,21 @@ mnemonad push ~/my-data
 A mnemonic works instead of a raw key: `--phrase "word1 word2 ..."`. `--key` and
 `MNEMONAD_KEY` both take precedence over `--phrase`.
 
+Or sign in with a passkey instead of any key at all:
+
+```bash
+mnemonad push ~/my-data --passkey
+```
+
+This opens the explorer's `/cli-auth` page in your default browser to complete a WebAuthn
+sign-in — no key ever touches this machine's disk or environment, only signatures relayed
+back for the duration of that one command. It needs a passkey already registered through the
+explorer (`--passkey` only signs in, it doesn't create one), a browser to complete the
+prompt in, and someone available to click through it — so it's a good fit for a human running
+a command by hand, not for scripts or CI (use `--key`/`MNEMONAD_KEY` there instead). See
+[`docs/wallet/passkey-accounts.md`](../docs/wallet/passkey-accounts.md) for how the account
+is derived and what this flow does and doesn't send anywhere.
+
 `pull`, `info` and `diff` work without a key for public (unencrypted) streams. A key is
 required for encrypted streams that use wallet-based encryption (not needed for
 password-based encryption — see below), and for any `push`.
@@ -131,13 +179,19 @@ chain.
 ```bash
 mnemonad push ~/my-data
 
-# prints the new stream id, e.g.:
-#   created: 123
+# prints the new stream id in hex, e.g.:
+#   created: 0x68d9736257f0d2da3c848666a4b36c4b9f18eda7e4dfba655599c47560d8a4b5
 #   version 1 pushed (full snapshot, gzip compressed)
+
+# examples below use `123` as a stand-in for whatever id you actually got back —
+# decimal or hex both work as input, see "Usage" above
 ```
 
 By default a new stream is public (unencrypted). Encrypting one takes a method — the CLI
-never picks for you, since both are reachable from the same invocation:
+never picks for you, since both are reachable from the same invocation. See
+[`../docs/encryption/encryption.md`](../docs/encryption/encryption.md) (and its
+[password](../docs/encryption/password.md)/[signature](../docs/encryption/signature.md)
+pages) for how each actually works and the trade-off each makes:
 
 ```bash
 # Keyed by a password: anyone who knows it can read the stream, from any machine.
@@ -187,7 +241,7 @@ mnemonad info 123 ~/my-data
   chain:           testnet
   your wallet:     0x06bc6420b37a4898424429dcfa236f0065e12279
 
-stream: 123
+stream: 0x68d9736257f0d2da3c848666a4b36c4b9f18eda7e4dfba655599c47560d8a4b5
   owner:           0x06bc6420b37a4898424429dcfa236f0065e12279 (you)
   encrypted:       no
   versions:        3
@@ -228,6 +282,23 @@ mnemonad push 123 ~/my-data --manifest
 # subsequent pushes are skipped when nothing has changed locally
 ```
 
+`--manifest` writes `.mnemonad` into the folder, recording the stream id, version and file
+hashes. With it, later commands on the same folder don't need the id typed again:
+
+```bash
+mnemonad push ~/my-data --manifest          # no id — read from .mnemonad
+mnemonad pull ~/my-data --manifest          # same
+mnemonad diff ~/my-data --manifest          # same
+```
+
+If no id is given and there's no `.mnemonad` yet (or `--manifest` wasn't passed), the usual
+`stream-id is required` error is thrown.
+
+`info` is the one exception that doesn't require `--manifest` to react to a manifest: being
+read-only, it always peeks at `.mnemonad` in `<path>` and reports what it finds — a note that
+one's available (with its id) if you left `--manifest` off, or a note if the id you gave
+doesn't match the one recorded in the folder's own manifest.
+
 ### Watch a folder (auto push + pull)
 
 ```bash
@@ -261,6 +332,23 @@ just a faster-replay optimization.
 mnemonad compact 123 ~/my-data
 ```
 
+### Burn a stream
+
+Permanently destroys the stream: the ERC-721 token and its metadata are gone, and — because
+ids are deterministic — re-creating a stream with the same id afterward does **not** recover
+the old data; the contract deliberately marks a burned id as permanently used. Deployed
+CODE-tier item bytes physically survive on-chain regardless — this removes the stream as a
+usable, readable thing, not necessarily every trace of its bytes. Requires **`--yes`**: run
+without it first to see what would be destroyed (owner, version count, on-chain size) before
+committing.
+
+```bash
+mnemonad burn 123
+# prints stream/chain/versions/size, then refuses to proceed without --yes
+
+mnemonad burn 123 --yes
+```
+
 ### Repair a corrupt stream with a force snapshot
 
 If a diff patch was pushed against a stale base (e.g. a race condition in `watch`),
@@ -272,6 +360,63 @@ mnemonad push 123 ~/my-data --force-snapshot
 # restore() will recover from this snapshot, skipping any corrupt diffs before it
 ```
 
+### Vector search (optional)
+
+Builds a local, plain (non-dot-prefixed) `search_index.db` at the folder root, using a local
+embedding model — no API key, nothing sent anywhere. Because it's a plain file, it rides
+through the next `push` like anything else in the folder, so anyone who later `pull`s the
+stream gets a ready-to-search index with no re-embedding of their own.
+
+```bash
+mnemonad index ~/my-data
+# embeds every changed text file since the last run (skips unchanged ones); binary files
+# are skipped entirely
+
+mnemonad search ~/my-data "how does chunking work"
+# 1. chunks.txt (chunk 0, distance 0.5838)
+#    one byte slips inward the boundaries hold their ground only one chunk moves
+
+mnemonad push ~/my-data
+# search_index.db is included automatically — it's just a file in the folder
+```
+
+The built-in model is `minishlab/potion-base-8M`: static embeddings in plain JS, no native
+code, a 31 MB download on first use, and a whole folder embedded in milliseconds. For better
+results on paraphrased queries, MiniLM is available as an optional extension (about 450 MB
+installed, most of it ONNX Runtime):
+
+```bash
+npm install -g mnemonad-search-transformers
+mnemonad index ~/my-data --model minilm
+```
+
+An index keeps the model it was built with, and `search` always uses it. To switch an existing
+index to another model, add `--rebuild`. See `docs/search.md` in the repository for how the two
+compare on this project's own data.
+
+`push` can also keep the index current for you: `--index` runs the same update right before pushing,
+with the push's own `--exclude`, so the index always covers exactly what the push uploads.
+If indexing fails (the first-time model download, say), nothing is pushed:
+
+```bash
+mnemonad push ~/my-data --index
+#   updating search index...
+#   index: 1 file(s) re-embedded, 0 removed (3 chunks)
+
+mnemonad watch <stream-id> ~/my-data --index
+# re-indexes before every automatic push; the model loads once for the whole session
+```
+
+A plain `push` of a folder that has an index checks it first. It doesn't load the model and
+doesn't touch the file. If files changed since the index was built, it says so and suggests
+`--index`, because a stale index would keep returning the old text's passages.
+
+See [`../docs/search.md`](../docs/search.md) for the whole process, and why the index stays
+diff-friendly on repeated pushes.
+
+A pushed index also turns on a search box in the explorer's file browser for that stream.
+The search runs in the browser on the same file and gives the same ranking as `mnemonad search`.
+
 ## End-to-end workflow
 
 Create a stream, verify what was stored, then roll back to an earlier version:
@@ -281,8 +426,10 @@ export MNEMONAD_KEY=0xabc123...
 
 # 1. first push — creates the stream
 mnemonad push ~/my-data
-#   created: 123
+#   created: 0x68d9736257f0d2da3c848666a4b36c4b9f18eda7e4dfba655599c47560d8a4b5
 #   version 1 pushed (full snapshot, gzip compressed)
+# (the rest of this walkthrough keeps using 123 as a stand-in for that id — both
+# forms work as input, see "Usage" above)
 
 # 2. verify: restore into a scratch folder and compare against the original
 mnemonad pull 123 ~/verify-tmp
@@ -318,10 +465,13 @@ mnemonad pull 123 ~/my-data-v1 --version 1
    the on-chain version.
 5. **watch** — combines push and pull in a loop. A filesystem watcher triggers a debounced
    push on local changes. A poll interval checks the remote stream for new versions and
-   pulls them if found. Push and pull never run concurrently. Monad's registry has no
-   "expected prior length" guard on push, so `watch` re-checks the remote length itself
-   right before pushing and resyncs if it has moved — a best-effort narrowing of the race
-   window, not a hard guarantee.
+   pulls them if found. Push and pull never run concurrently. The contract *does* check an
+   `expectedLength` atomically on every write, so two writers can never land at the same
+   index — one just reverts. What it can't check is content: it stores opaque bytes, with no
+   way to verify a diff patch is actually consistent with the real previous item. `watch`
+   re-checks the remote length and resyncs before pushing specifically to narrow that
+   separate window — a best-effort narrowing, not a hard guarantee, since only an atomic
+   on-chain check (which it already has, for the index) could close it outright.
 6. **compact** — drops all existing history on-chain and pushes the current folder as a
    single fresh full snapshot, speeding up future replay after many incremental syncs.
 
@@ -329,7 +479,8 @@ mnemonad pull 123 ~/my-data-v1 --version 1
 
 The following are always excluded from snapshots: `node_modules`, `.git`, `.env`,
 `.DS_Store`, `.mnemonad`, `.claude`, `pnpm-lock.yaml`, `package-lock.json`. Add more with
-`--exclude`.
+`--exclude`. `search_index.db` (see "Vector search" above) is deliberately **not** on this
+list — it's a plain file, meant to be pushed like any other.
 
 ## Dependencies
 
@@ -337,4 +488,7 @@ The following are always excluded from snapshots: `node_modules`, `.git`, `.env`
 |---|---|
 | `mnemonad` | On-chain stream primitive (this repo's `js/`) |
 | `monadsync` | Folder-diff / snapshot layer on top of `mnemonad` (this repo's `monadsync/`) |
+| `better-sqlite3`, `@sqliteai/sqlite-vector` | The search index: SQLite with vector search (`lib/search/`) |
+| `@huggingface/tokenizers` | Tokenizer for the built-in embedding model (pure JS) |
+| `mnemonad-search-transformers` | *Not a dependency* — the optional MiniLM extension, installed separately and found at runtime |
 | `viem` | Monad client / key management |

package/bin/mnemonad.js

@@ -17,7 +17,9 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
-import { push, pull, info, diff, watch, compact } from '../lib/commands/index.js';
+import { push, pull, info, diff, watch, compact, burn, buildIndex, search } from '../lib/commands/index.js';
+import { parseQualifiedStreamId } from '../lib/commands/shared.js';
+import { closePasskeyBridge } from '../lib/passkeyBridge.js';
 import defaultConfig from '../mnemonad.config.js';
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -39,7 +41,7 @@ const CONFIG = defaultConfig || {};
 // Same default the explorer dApp uses (explorer/src/mnemonad/presignProvider.js) — a
 // public read gateway so pulling/diffing/inspecting a stream with IPFS-offloaded items
 // works out of the box, with no setup, for anyone who didn't push it themselves.
-const DEFAULT_IPFS_GATEWAY = CONFIG.gatewayUrl || 'https://gateway.pinata.cloud/ipfs/';
+const DEFAULT_IPFS_GATEWAY = CONFIG.gatewayUrl || 'https://azure-casual-firefly-850.mypinata.cloud/ipfs/';
 
 // The deployed presign server (presign-server/) this project runs by default — see its own
 // README for what it does. Pushing an item too big to fit on-chain uses this automatically
@@ -47,6 +49,10 @@ const DEFAULT_IPFS_GATEWAY = CONFIG.gatewayUrl || 'https://gateway.pinata.cloud/
 // alternative for anyone who'd rather supply their own.
 const DEFAULT_PRESIGN_URL = CONFIG.presignUrl || null;
 
+// See mnemonad.config.js's own comment on why this has to be a real deployed domain, not a
+// placeholder — --passkey opens it to run the WebAuthn ceremony there.
+const DEFAULT_AUTH_ORIGIN = CONFIG.authOrigin || 'https://mnemonad.vercel.app';
+
 const USAGE = `mnemonad v${VERSION} — sync local folders to a versioned, diffed stream on Monad
 
 Usage:
@@ -56,10 +62,18 @@ Usage:
   mnemonad diff <stream-id> <path> [options]      List local files added/modified/deleted vs the on-chain version
   mnemonad watch <stream-id> <path> [options]     Watch folder and auto-push/pull
   mnemonad compact <stream-id> <path> [options]   Truncate old history, push a fresh snapshot
+  mnemonad burn <stream-id> --yes [options]       Permanently destroy a stream (irreversible)
+  mnemonad index <path> [options]                 Build/update a local vector-search index
+                                                   for the folder (optional; see below)
+  mnemonad search <path> <query> [options]        Search a folder's vector index
 
 <path> is always required wherever a command touches a folder — the CLI never assumes the
-current directory. The only exception is \`mnemonad info\` with no stream-id, which just
-checks your configured chain/wallet and needs no folder at all.
+current directory. The exceptions are \`mnemonad info\` with no stream-id (just checks your
+configured chain/wallet) and \`mnemonad burn\`, which takes no folder at all.
+
+<stream-id> also accepts the network-qualified form shown in the explorer's URLs —
+testnet-0x648f18… — paste it straight out of a /stream/<id> link. It sets --chain to match;
+pass --chain too only if it agrees, or the command refuses rather than guess which one you meant.
 
 Options:
   --chain <name>            Chain: testnet, mainnet, local (default: testnet)
@@ -67,11 +81,17 @@ Options:
   --contract-address <addr> Registry address to use instead of the chain's known deployment
                             (required with --chain local)
   --gateway-url <url>       IPFS gateway for reading externally-offloaded items
-                            (default: https://gateway.pinata.cloud/ipfs/, or MNEMONAD_IPFS_GATEWAY env var)
+                            (default: this project's Pinata dedicated gateway, or MNEMONAD_IPFS_GATEWAY env var)
   --presign-url <url>       Presign server for paid IPFS uploads with no Pinata credential
                             (default: the deployed server in mnemonad.config.js, or MNEMONAD_PRESIGN_URL env var)
   --key <privkey>           Monad private key (or set MNEMONAD_KEY env var)
   --phrase <mnemonic>       Mnemonic phrase
+  --passkey                 Sign with a passkey instead of --key/--phrase: opens the explorer
+                            in your browser to sign in with WebAuthn, then relays signing
+                            requests to that tab for this command. Interactive only — not for
+                            scripts/CI. See docs/wallet/passkey-accounts.md
+  --auth-origin <url>       Explorer deployment --passkey opens (default: this project's
+                            explorer deployment, or MNEMONAD_AUTH_ORIGIN env var)
   --version <n>             Version to restore/compare (pull, diff, info; default: latest)
   --exclude <p1,p2>         Extra exclude patterns (comma-separated)
   --no-compress             Disable gzip compression
@@ -80,13 +100,39 @@ Options:
                             signs for it). Implied by --password; required otherwise
   --password <pw>           Password to encrypt a new stream with, or decrypt an existing one
   --pinata-jwt <jwt>        Pinata JWT for IPFS offload of large files (or PINATA_JWT env var)
-  --manifest                Write/use .mnemonad manifest for faster change detection
+  --manifest                Write/use .mnemonad manifest for faster change detection.
+                            With no stream-id given, every command recovers it from an
+                            existing .mnemonad in <path> instead of requiring it explicitly
   --force-snapshot          Push a full snapshot regardless of prior history (repairs corrupt streams)
+  --index                   push/watch: update the folder's search index (search_index.db)
+                            before every push, so the stream is searchable right after a pull.
+                            Takes --db/--model/--chunk-size/--chunk-overlap like \`index\`
   --poll-interval <s>       Watch: seconds between remote checks (default: 2)
   --debounce <ms>           Watch: ms quiet period before pushing after a change (default: 1000)
   --push-only               Watch: disable auto-pull
   --pull-only               Watch: disable auto-push
+  --yes                     Required by burn — explicit opt-in for an irreversible action
+  --db <name>               index/search: vector-index filename (default: search_index.db)
+  --model <name>            index / --index: embedding model. \`potion\` (built in, the default for
+                            a new index) or \`minilm\` (better on paraphrased queries; needs the
+                            optional extension: npm install -g mnemonad-search-transformers),
+                            or a full model id. Without it, an existing index keeps its own
+                            model. \`search\` always uses the index's own model. All local —
+                            no API key, nothing sent anywhere
+  --rebuild                 index / --index: start the index over (the way to switch models);
+                            the next push uploads the whole index again
+  --chunk-size <n>          index: target characters per chunk (default: 1000)
+  --chunk-overlap <n>       index: characters of overlap between chunks (default: 150)
+  --limit, -k <n>           search: number of results (default: 5)
   --help                    Show this help
+
+index/search are optional and independent of push/pull — a folder with no search_index.db
+just has no search capability. \`index\` writes a plain (non-dot-prefixed) file at the
+folder's root, so it rides through the next \`push\` like any other file: whoever pulls the
+stream gets the index already built, with no re-embedding of their own. \`push --index\` and
+\`watch --index\` run \`index\` for you before each push, and a plain \`push\` of a folder whose
+index has fallen behind its files says so. See docs/search.md in the repository for how the
+index works and stays diff-friendly on repeated pushes.
 `;
 
 function parseArgs(argv) {
@@ -103,6 +149,8 @@ function parseArgs(argv) {
         presignUrl: process.env.MNEMONAD_PRESIGN_URL || DEFAULT_PRESIGN_URL,
         key: null,
         phrase: null,
+        passkey: false,
+        authOrigin: process.env.MNEMONAD_AUTH_ORIGIN || DEFAULT_AUTH_ORIGIN,
         version: null,
         exclude: null,
         compress: 'gzip',
@@ -111,11 +159,20 @@ function parseArgs(argv) {
         password: null,
         pinataJwt: process.env.PINATA_JWT || null,
         manifest: false,
+        index: false,
+        rebuild: false,
         forceSnapshot: false,
         pollInterval: 2,
         debounce: 1000,
         pushOnly: false,
         pullOnly: false,
+        yes: false,
+        query: null,
+        searchDb: null,
+        model: null,
+        chunkSize: null,
+        chunkOverlap: null,
+        limit: null,
     };
 
     const raw = argv.slice(2);
@@ -134,27 +191,58 @@ function parseArgs(argv) {
     // command except a bare `info`) fails fast with a clear error instead of silently
     // operating on whatever directory the CLI happened to be run from.
     // A stream id is a decimal bigint or a 0x-prefixed hex string; anything else is a path.
-    const isStreamId = (s) => /^\d+$/.test(s) || /^0x[0-9a-fA-F]+$/.test(s);
+    //
+    // Also accepted: the network-qualified form the explorer's own URLs use —
+    // `<network>-0x<hex>`, e.g. `testnet-0x648f18…` — since that's what an agent naturally
+    // has in hand after pulling an id straight out of a /stream/<id> link. A qualified id
+    // names the chain the same way the URL does; parseQualifiedStreamId (shared.js, same
+    // split the explorer's own parseStreamRouteId does) records which one (chainFromId,
+    // below) so it can settle --chain once flags are parsed too.
+    const isStreamId = (s) => /^\d+$/.test(s) || /^0x[0-9a-fA-F]+$/.test(s) || !!parseQualifiedStreamId(s);
+
+    let chainFromId = null;
+    // Strips a recognized `<network>-` prefix and records the network it named, so every
+    // downstream command only ever sees the bare id it already knows how to parse
+    // (formatStreamId, `new Mnemonad({id})`, etc. never learn this form exists).
+    const takeStreamId = (arg) => {
+        const qualified = parseQualifiedStreamId(arg);
+        if (!qualified) return arg;
+        chainFromId = qualified.network;
+        return qualified.id;
+    };
+
+    // `-k` is the one short flag — it has to end the positionals too, or `search`'s
+    // join-the-rest query below swallows it (`search ./f slow and steady -k 3` once searched
+    // for "slow and steady -k 3").
+    const isFlag = (arg) => arg.startsWith('--') || arg === '-k';
     const positionals = [];
-    while (i < raw.length && !raw[i].startsWith('--')) {
+    while (i < raw.length && !isFlag(raw[i])) {
         positionals.push(raw[i]);
         i++;
     }
-    if (positionals.length === 2) {
-        args.streamId = positionals[0];
+    if (args.command === 'search') {
+        // <path> <query...> — everything after the path is the query, joined back with spaces
+        // so an unquoted multi-word query (`mnemonad search ./docs how does chunking work`)
+        // works the same as a quoted one. Never a stream id — `search` doesn't take one.
+        args.path = positionals[0] || null;
+        args.query = positionals.length > 1 ? positionals.slice(1).join(' ') : null;
+    } else if (positionals.length === 2) {
+        args.streamId = takeStreamId(positionals[0]);
         args.path = positionals[1];
     } else if (positionals.length === 1) {
         if (isStreamId(positionals[0])) {
-            args.streamId = positionals[0];
+            args.streamId = takeStreamId(positionals[0]);
         } else {
             args.path = positionals[0];
         }
     }
 
+    let sawChainFlag = false;
     while (i < raw.length) {
         const flag = raw[i];
         if (flag === '--chain' && i + 1 < raw.length) {
             args.chain = raw[++i];
+            sawChainFlag = true;
         } else if (flag === '--rpc-url' && i + 1 < raw.length) {
             args.rpcUrl = raw[++i];
         } else if (flag === '--contract-address' && i + 1 < raw.length) {
@@ -167,6 +255,10 @@ function parseArgs(argv) {
             args.key = raw[++i];
         } else if (flag === '--phrase' && i + 1 < raw.length) {
             args.phrase = raw[++i];
+        } else if (flag === '--passkey') {
+            args.passkey = true;
+        } else if (flag === '--auth-origin' && i + 1 < raw.length) {
+            args.authOrigin = raw[++i];
         } else if (flag === '--version' && i + 1 < raw.length) {
             args.version = raw[++i];
         } else if (flag === '--exclude' && i + 1 < raw.length) {
@@ -183,6 +275,10 @@ function parseArgs(argv) {
             args.pinataJwt = raw[++i];
         } else if (flag === '--manifest') {
             args.manifest = true;
+        } else if (flag === '--index') {
+            args.index = true;
+        } else if (flag === '--rebuild') {
+            args.rebuild = true;
         } else if (flag === '--force-snapshot') {
             args.forceSnapshot = true;
         } else if (flag === '--poll-interval' && i + 1 < raw.length) {
@@ -193,10 +289,34 @@ function parseArgs(argv) {
             args.pushOnly = true;
         } else if (flag === '--pull-only') {
             args.pullOnly = true;
+        } else if (flag === '--yes') {
+            args.yes = true;
+        } else if (flag === '--db' && i + 1 < raw.length) {
+            args.searchDb = raw[++i];
+        } else if (flag === '--model' && i + 1 < raw.length) {
+            args.model = raw[++i];
+        } else if (flag === '--chunk-size' && i + 1 < raw.length) {
+            args.chunkSize = Number(raw[++i]);
+        } else if (flag === '--chunk-overlap' && i + 1 < raw.length) {
+            args.chunkOverlap = Number(raw[++i]);
+        } else if ((flag === '--limit' || flag === '-k') && i + 1 < raw.length) {
+            args.limit = Number(raw[++i]);
         }
         i++;
     }
 
+    if (chainFromId) {
+        if (sawChainFlag && args.chain !== chainFromId) {
+            console.error(
+                `Error: the stream id names network '${chainFromId}', but --chain '${args.chain}' was\n` +
+                `  also given — they disagree. Drop --chain to use the id's network, or pass\n` +
+                `  --chain ${chainFromId} to match it.`
+            );
+            _realExit(1);
+        }
+        args.chain = chainFromId;
+    }
+
     return args;
 }
 
@@ -208,6 +328,22 @@ console.log(`mnemonad v${VERSION}`);
 // anything in the RPC/fetch stack unref's its own I/O (see the process.exit note above).
 const keepAlive = setInterval(() => {}, 60_000);
 
+// --passkey's browser tab shows a result line when the command finishes (see
+// closePasskeyBridge()) rather than a bare "done" — commands don't return a summary
+// explicitly, so this captures their own last console.log line instead, the same thing this
+// terminal already sees. Only wired up when --passkey is in play; every other run's
+// console.log is untouched.
+const logLines = [];
+const originalConsoleLog = console.log;
+if (args.passkey) {
+    console.log = (...parts) => {
+        originalConsoleLog(...parts);
+        logLines.push(parts.join(' '));
+    };
+}
+let succeeded = true;
+let errorMessage = null;
+
 try {
     if (args.command === 'push') {
         await push(args);
@@ -221,6 +357,12 @@ try {
         await watch(args);
     } else if (args.command === 'compact') {
         await compact(args);
+    } else if (args.command === 'burn') {
+        await burn(args);
+    } else if (args.command === 'index') {
+        await buildIndex(args);
+    } else if (args.command === 'search') {
+        await search(args);
     } else {
         console.error('Unknown command:', args.command);
         console.log(USAGE);
@@ -229,15 +371,26 @@ try {
 } catch (err) {
     if (err._isProcessExit) {
         process.exitCode = err._exitCode;
+        succeeded = err._exitCode === 0;
     } else if (err._isUserError) {
         // Expected, actionable failure — message only, no stack trace.
         console.error('Error:', err.message);
         process.exitCode = 1;
+        succeeded = false;
     } else {
         console.error('Error:', err.message);
         if (err.stack) console.error(err.stack);
         process.exitCode = 1;
+        succeeded = false;
     }
+    errorMessage = err.message;
 } finally {
+    console.log = originalConsoleLog;
+    // No-op when --passkey was never used — see passkeyBridge.js. Runs whether the command
+    // succeeded or failed, so a browser tab left open on a failed push doesn't linger.
+    closePasskeyBridge({
+        ok: succeeded,
+        summary: succeeded ? (logLines.filter(Boolean).pop() || 'Done.') : (errorMessage || 'Failed.'),
+    });
     clearInterval(keepAlive);
 }

package/lib/bridgeCodec.js

@@ -0,0 +1,12 @@
+/**
+ * JSON can't carry BigInt, and viem's transaction-request objects use BigInt for gas/value/
+ * fee fields — so a transaction going out over `--passkey`'s loopback WebSocket bridge
+ * (passkeyBridge.js) to the browser tab is wrapped through this first.
+ *
+ * Must produce exactly what explorer/src/wallet/bridgeCodec.js's `decodeFromBridge` expects
+ * — the two sides are never bundled together (separate packages), so keep them in sync by
+ * hand if either changes.
+ */
+export function encodeForBridge(value) {
+	return JSON.parse(JSON.stringify(value, (_key, v) => (typeof v === 'bigint' ? { __bigint__: v.toString() } : v)));
+}