mnemonad-cli 0.2.0 → 0.3.1

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
@@ -63,6 +77,8 @@ mnemonad diff <stream-id> <path> [options]     List files added/modified/deleted
 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
@@ -88,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 |
@@ -100,11 +118,19 @@ Every command prints the installed CLI version as its first line of output.
 | `--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. 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) |
+| `--detach` | `push`: build the next version here, send it from a background process, and return right away. Existing streams only. See "Push in the background" below |
+| `--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
@@ -125,6 +151,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`.
@@ -309,6 +350,48 @@ mnemonad burn 123
 mnemonad burn 123 --yes
 ```
 
+### Push in the background
+
+A push spends most of its time waiting for the chain. `--detach` does everything that can
+fail for your own reasons first, here and now: the owner check, unlocking, `--index`, "no
+changes", and the balance against the estimated cost. Then it hands only the sending to a
+background process and returns:
+
+```bash
+mnemonad push ~/my-data --manifest --detach
+#   version 8 prepared (diff, gzip compressed, 2.1 KB)
+#   estimated cost: 0.0041 MON
+#   stream: 0x68d9…
+#   sending in the background: job 8f3c1a2b (pid 41210)
+#   log:   ~/.cache/mnemonad/jobs/8f3c1a2b/push.log
+#   check: mnemonad info ~/my-data --manifest
+```
+
+- **The version is frozen when the command runs.** Edits made after it returns go into the
+  next push, not this one.
+- **Existing streams only.** It needs a stream id, or `--manifest` on a folder that has a
+  `.mnemonad`. Create a stream with a normal push first. `--passkey` can't be used: the browser
+  tab that signs for it closes when the command exits.
+- **The next command waits for it.** A `push`, `pull`, `compact` or `watch` of the same stream
+  waits until the background push has finished, so nothing builds on, or restores, the version
+  before it. A push from the same wallet to another stream waits too, so the two don't race for
+  one nonce. `diff` only notes that a push is still sending.
+- **Results:** `mnemonad info <path>` shows the last background push for the stream, and when
+  it failed, why. If one fails, the next command on that stream also prints a warning, once.
+- **Nothing half-lands.** The background process refuses to send a version whose base is gone
+  (the stream changed after it was prepared), and the contract rejects any write that doesn't
+  land at the index it names. A failed background push leaves the stream as it was. Push again.
+- **Secrets stay in memory.** The key, the password and a Pinata JWT are handed to the
+  background process over a pipe. They are never written to the job folder, the log, or the
+  process list.
+- If the background process is killed mid-send, the job is reported as failed the next time a
+  command looks at it. A large push that was staged over several transactions, or paid for an
+  IPFS upload, can't be resumed. A paid but unused upload can be refunded after the gateway's
+  time limit, with the SDK's `MnemonadUploadGateway.refund()` (the CLI has no command for it).
+
+Jobs live in `~/.cache/mnemonad/jobs/` (set `MNEMONAD_JOBS_DIR` to move them). Finished ones are
+removed after 14 days.
+
 ### 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`),
@@ -320,6 +403,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:
@@ -368,10 +508,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.
 
@@ -379,7 +522,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
 
@@ -387,4 +531,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,8 +17,10 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
-import { push, pull, info, diff, watch, compact, burn } 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 { runPushJob } from '../lib/jobs.js';
 import defaultConfig from '../mnemonad.config.js';
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -40,7 +42,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
@@ -48,6 +50,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:
@@ -58,6 +64,9 @@ Usage:
   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 exceptions are \`mnemonad info\` with no stream-id (just checks your
@@ -73,11 +82,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
@@ -90,12 +105,39 @@ Options:
                             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)
+  --detach                  push: build the next version here, send it from a background process,
+                            and return right away. Existing streams only (an id, or --manifest).
+                            Later pushes and pulls of that stream wait for it; \`mnemonad info\`
+                            shows how it went
+  --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) {
@@ -112,6 +154,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',
@@ -120,12 +164,21 @@ function parseArgs(argv) {
         password: null,
         pinataJwt: process.env.PINATA_JWT || null,
         manifest: false,
+        index: false,
+        rebuild: false,
         forceSnapshot: false,
+        detach: 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);
@@ -164,12 +217,22 @@ function parseArgs(argv) {
         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) {
+    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) {
@@ -198,6 +261,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) {
@@ -214,8 +281,14 @@ 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 === '--detach') {
+            args.detach = true;
         } else if (flag === '--poll-interval' && i + 1 < raw.length) {
             args.pollInterval = Number(raw[++i]);
         } else if (flag === '--debounce' && i + 1 < raw.length) {
@@ -226,6 +299,16 @@ function parseArgs(argv) {
             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++;
     }
@@ -253,6 +336,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);
@@ -268,6 +367,13 @@ try {
         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 if (args.command === '__push-job') {
+        // The detached half of `push --detach` (lib/jobs.js) — never typed by a person.
+        await runPushJob(args.path);
     } else {
         console.error('Unknown command:', args.command);
         console.log(USAGE);
@@ -276,15 +382,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)));
+}

package/lib/chainClient.js

@@ -8,6 +8,8 @@
 import { createPublicClient, createWalletClient, defineChain, http } from 'viem';
 import { privateKeyToAccount, mnemonicToAccount } from 'viem/accounts';
 import { monad, monadTestnet } from 'viem/chains';
+import { openPasskeyBridge } from './passkeyBridge.js';
+import { userError } from './commands/shared.js';
 
 /**
  * CLI `--chain` name -> { viem chain object, Mnemonad network shorthand for
@@ -45,10 +47,20 @@ function normalizeKey(key) {
 	return key.startsWith('0x') ? key : `0x${key}`;
 }
 
-function resolveAccount(args) {
+/**
+ * `--key`/`--phrase`/`MNEMONAD_KEY` resolve synchronously; `--passkey` doesn't (it opens a
+ * browser tab and waits for a human to complete a WebAuthn prompt) — see
+ * passkeyBridge.js. That's the one thing that makes this function, and therefore
+ * `makeChainClient`, async rather than the plain synchronous lookup it used to be.
+ */
+async function resolveAccount(args) {
 	const key = args.key || process.env.MNEMONAD_KEY;
+	if (args.passkey && (key || args.phrase)) {
+		throw userError('--passkey cannot be combined with --key/--phrase/MNEMONAD_KEY — pick one signing method.');
+	}
 	if (key) return privateKeyToAccount(normalizeKey(key));
 	if (args.phrase) return mnemonicToAccount(args.phrase);
+	if (args.passkey) return openPasskeyBridge(args);
 	return null;
 }
 
@@ -60,16 +72,17 @@ function resolveAccount(args) {
  * `requireWalletClient` themselves, so the "no key" error only surfaces where it's
  * actually required.
  *
- * @param {Object} args - parsed CLI args: `chain`, `rpcUrl`, `key`, `phrase`, `contractAddress`
- * @returns {{
+ * @param {Object} args - parsed CLI args: `chain`, `rpcUrl`, `key`, `phrase`, `passkey`,
+ *   `authOrigin`, `contractAddress`
+ * @returns {Promise<{
  *   publicClient: Object,
  *   walletClient: ?Object,
  *   account: ?Object,
  *   contractAddress: string,
  *   chain: Object,
- * }}
+ * }>}
  */
-export function makeChainClient(args) {
+export async function makeChainClient(args) {
 	let chain, contractAddress;
 	if (args.chain === 'local') {
 		// Dev/test only — see localChain() above.
@@ -95,7 +108,7 @@ export function makeChainClient(args) {
 	const transport = http(args.rpcUrl);
 	const publicClient = createPublicClient({ chain, transport });
 
-	const account = resolveAccount(args);
+	const account = await resolveAccount(args);
 	const walletClient = account ? createWalletClient({ chain, transport, account }) : null;
 
 	return { publicClient, walletClient, account, contractAddress, chain };
@@ -111,7 +124,8 @@ export function requireWalletClient(client) {
 		// first thing anyone hits before configuring a key, and a stack trace through
 		// chainClient makes an actionable one-liner look like a crash.
 		const err = new Error(
-			'No signing key. Set the MNEMONAD_KEY env var to a private key, or pass --key / --phrase.'
+			'No signing key. Set the MNEMONAD_KEY env var to a private key, pass --key / --phrase, ' +
+			'or pass --passkey to sign in with a passkey via the browser.'
 		);
 		err._isUserError = true;
 		throw err;