mnemonad-cli 0.1.0 → 0.2.0

package/README.md

@@ -12,8 +12,23 @@ signer's own wallet key.
 
 ## Installation
 
-This package lives in the monorepo alongside `mnemonad` and `monadsync` and is not yet
-published. From the repo root:
+### From npm (recommended)
+
+```bash
+npm install -g mnemonad-cli
+mnemonad --help
+```
+
+To pick up a new release later:
+
+```bash
+npm update -g mnemonad-cli
+```
+
+### From this repo (for development)
+
+This package lives in the monorepo alongside `mnemonad` and `monadsync`, linked through a
+pnpm workspace at the repo root. From the repo root:
 
 ```bash
 cd cli
@@ -21,7 +36,7 @@ pnpm install
 node bin/mnemonad.js --help
 ```
 
-Or link it for a global `mnemonad` command:
+Or link it for a global `mnemonad` command that tracks your local checkout:
 
 ```bash
 cd cli
@@ -47,15 +62,22 @@ 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
 ```
 
 `<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.
 
@@ -76,12 +98,13 @@ 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) |
 | `--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 |
 | `--help` | Show help |
 
 ### Authentication
@@ -116,13 +139,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.
@@ -172,7 +201,7 @@ mnemonad info 123 ~/my-data
   chain:           testnet
   your wallet:     0x06bc6420b37a4898424429dcfa236f0065e12279
 
-stream: 123
+stream: 0x68d9736257f0d2da3c848666a4b36c4b9f18eda7e4dfba655599c47560d8a4b5
   owner:           0x06bc6420b37a4898424429dcfa236f0065e12279 (you)
   encrypted:       no
   versions:        3
@@ -213,6 +242,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
@@ -246,6 +292,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`),
@@ -266,8 +329,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

package/bin/mnemonad.js

@@ -17,7 +17,8 @@ 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 } from '../lib/commands/index.js';
+import { parseQualifiedStreamId } from '../lib/commands/shared.js';
 import defaultConfig from '../mnemonad.config.js';
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -56,10 +57,15 @@ 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)
 
 <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)
@@ -80,12 +86,15 @@ 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)
   --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
   --help                    Show this help
 `;
 
@@ -116,6 +125,7 @@ function parseArgs(argv) {
         debounce: 1000,
         pushOnly: false,
         pullOnly: false,
+        yes: false,
     };
 
     const raw = argv.slice(2);
@@ -134,27 +144,48 @@ 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;
+    };
+
     const positionals = [];
     while (i < raw.length && !raw[i].startsWith('--')) {
         positionals.push(raw[i]);
         i++;
     }
     if (positionals.length === 2) {
-        args.streamId = positionals[0];
+        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) {
@@ -193,10 +224,24 @@ function parseArgs(argv) {
             args.pushOnly = true;
         } else if (flag === '--pull-only') {
             args.pullOnly = true;
+        } else if (flag === '--yes') {
+            args.yes = true;
         }
         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;
 }
 
@@ -221,6 +266,8 @@ try {
         await watch(args);
     } else if (args.command === 'compact') {
         await compact(args);
+    } else if (args.command === 'burn') {
+        await burn(args);
     } else {
         console.error('Unknown command:', args.command);
         console.log(USAGE);

package/lib/chainClient.js

@@ -107,6 +107,13 @@ export function makeChainClient(args) {
  */
 export function requireWalletClient(client) {
 	if (!client.walletClient) {
-		throw new Error('No signing key. Use --key, --phrase, or MNEMONAD_KEY env var');
+		// Marked as a user error so the CLI boundary prints the message alone: this is the
+		// 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.'
+		);
+		err._isUserError = true;
+		throw err;
 	}
 }

package/lib/commands/burn.js

@@ -0,0 +1,59 @@
+import Mnemonad from 'mnemonad';
+import { makeChainClient, requireWalletClient } from '../chainClient.js';
+import { assertStreamOwner, formatStreamId, formatBytes } from './shared.js';
+
+/**
+ * Destroys a stream permanently: burns the ERC-721 token and clears its metadata and
+ * wrapped encryption key (`contracts/src/Mnemonad.sol`'s own `burn()`). Irreversible, and
+ * re-creating a stream with the same id afterward does NOT resurrect the old data — ids are
+ * deterministic, so the contract deliberately marks a burned id as permanently used rather
+ * than letting a fresh `create()` silently inherit old item records.
+ *
+ * Deployed CODE-tier item bytes physically survive on-chain regardless of burn — this
+ * removes the stream as a usable, readable thing, not necessarily every trace of its bytes.
+ *
+ * Requires `--yes`: the one command here that destroys something with no way back, so it
+ * refuses to run without an explicit, unambiguous opt-in rather than an interactive prompt
+ * a script could accidentally click through.
+ */
+export async function burn(args) {
+    if (!args.streamId) {
+        throw new Error('stream-id is required for burn');
+    }
+
+    const client = makeChainClient(args);
+    requireWalletClient(client);
+
+    const mn = new Mnemonad({
+        publicClient: client.publicClient,
+        walletClient: client.walletClient,
+        contractAddress: client.contractAddress,
+        id: args.streamId,
+    });
+
+    // Ownership checked before printing anything about the stream's contents — same
+    // reasoning as every other write command's own assertStreamOwner call.
+    await assertStreamOwner(mn, client.account.address);
+    await mn.initialize();
+
+    console.log('stream:      ', formatStreamId(mn.id));
+    console.log('chain:       ', args.chain);
+    console.log('versions:    ', mn.length);
+    console.log('binary size: ', formatBytes(mn.binaryLength));
+
+    if (!args.yes) {
+        const err = new Error(
+            'This permanently destroys the stream above: the ERC-721 token and its metadata\n' +
+            '  are gone, and re-creating a stream with this id afterward does NOT recover the\n' +
+            '  old data — there is no undo. (Deployed CODE-tier chunks physically survive on\n' +
+            '  chain regardless; this only removes the stream as a usable, readable thing.)\n' +
+            '  Re-run with --yes to actually burn it.'
+        );
+        err._isUserError = true;
+        throw err;
+    }
+
+    console.log('burning...');
+    await mn.burn();
+    console.log('  done —', formatStreamId(mn.id), 'is burned.');
+}

package/lib/commands/compact.js

@@ -10,6 +10,7 @@ import {
     assertStreamOwner,
     unlockStream,
     resolveOffloadParams,
+    discoverStreamId,
 } from './shared.js';
 
 /**
@@ -19,11 +20,15 @@ import {
  * to it.
  */
 export async function compact(args) {
+    const destPath = resolvePath(args.path, { mustExist: true });
+
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
     if (!args.streamId) {
         throw new Error('stream-id is required for compact');
     }
 
-    const destPath = resolvePath(args.path);
     const fsFolder = new FSFolder(destPath, makeExcludes(args));
 
     const counts = await countTree(fsFolder);

package/lib/commands/diff.js

@@ -8,6 +8,9 @@ import {
     formatPath,
     hashLocalTree,
     unlockStream,
+    formatStreamId,
+    folderExists,
+    discoverStreamId,
 } from './shared.js';
 
 export function compareFileMaps(localFiles, remoteFiles) {
@@ -36,13 +39,23 @@ export function compareFileMaps(localFiles, remoteFiles) {
 }
 
 export async function diff(args) {
-    if (!args.streamId) {
-        throw new Error('stream-id is required for diff');
-    }
     // Resolved up front (throws if missing) so a missing path fails fast, before any chain
     // work — see resolvePath()'s own comment for why this is never defaulted to cwd.
+    //
+    // Deliberately NOT `{ mustExist: true }`, unlike push/compact/watch: diffing a stream
+    // against a folder you haven't pulled yet is a legitimate question ("what would I get?"),
+    // and this command writes nothing either way. It is called out explicitly below though —
+    // "everything deleted" for a folder that never existed reads as data loss rather than as
+    // a wrong path.
     const destPath = resolvePath(args.path);
 
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
+    if (!args.streamId) {
+        throw new Error('stream-id is required for diff');
+    }
+
     const client = makeChainClient(args);
 
     const mn = new Mnemonad({
@@ -61,7 +74,7 @@ export async function diff(args) {
     const totalVersions = mn.length;
 
     if (totalVersions === 0) {
-        console.log('stream', args.streamId, 'has no versions yet — nothing to diff');
+        console.log('stream', formatStreamId(args.streamId), 'has no versions yet — nothing to diff');
         return;
     }
 
@@ -70,7 +83,13 @@ export async function diff(args) {
         throw new Error('version must be between 1 and ' + totalVersions);
     }
 
-    console.log('diff:', formatPath(destPath), 'vs', args.streamId, '(version ' + version + ' of ' + totalVersions + ')');
+    console.log('diff:', formatPath(destPath), 'vs', formatStreamId(args.streamId), '(version ' + version + ' of ' + totalVersions + ')');
+    // Said up front, before the file list: without it, a mistyped path produces a list of
+    // every file in the stream marked "deleted", which reads as data loss rather than as
+    // a folder that was never there.
+    if (!folderExists(destPath)) {
+        console.log('  note: local folder does not exist — everything below is listed as deleted');
+    }
     console.log('  restoring chain version...');
 
     let remoteFolder;

package/lib/commands/index.js

@@ -4,3 +4,4 @@ export { info } from './info.js';
 export { diff } from './diff.js';
 export { watch } from './watch.js';
 export { compact } from './compact.js';
+export { burn } from './burn.js';

package/lib/commands/info.js

@@ -6,6 +6,11 @@ import {
     formatBytes,
     localTreeHash,
     unlockStream,
+    formatStreamId,
+    folderExists,
+    discoverStreamId,
+    readManifest,
+    streamIdsEqual,
 } from './shared.js';
 
 export async function info(args) {
@@ -14,6 +19,32 @@ export async function info(args) {
     console.log('  chain:          ', args.chain);
     console.log('  your wallet:    ', client.account?.address || '(none)');
 
+    // Peek at .mnemonad whenever a path is given, regardless of --manifest and regardless
+    // of whether an id was given — info is read-only, so surfacing what's there costs
+    // nothing, and it's the only command where "you have a manifest but forgot the flag" or
+    // "you gave an id that doesn't match your own manifest" are worth a note rather than a
+    // silent mismatch.
+    const manifest = args.path ? await readManifest(resolvePath(args.path)) : null;
+
+    if (manifest?.streamId) {
+        if (!args.streamId) {
+            if (args.manifest) {
+                // Logs its own "using stream id from .mnemonad manifest: ..." line.
+                await discoverStreamId(args, resolvePath(args.path));
+            } else {
+                console.log(
+                    '  manifest:       ', formatStreamId(manifest.streamId),
+                    '(.mnemonad found — pass --manifest to use it without an id)'
+                );
+            }
+        } else if (!streamIdsEqual(manifest.streamId, args.streamId)) {
+            console.log(
+                '  manifest:       ', formatStreamId(manifest.streamId),
+                '(differs from the id given:', formatStreamId(args.streamId) + ')'
+            );
+        }
+    }
+
     if (!args.streamId) {
         return;
     }
@@ -33,7 +64,7 @@ export async function info(args) {
 
     const totalVersions = mn.length;
 
-    console.log('\nstream:', args.streamId);
+    console.log('\nstream:', formatStreamId(args.streamId));
 
     const owner = await mn.owner().catch(() => null) || '(unknown)';
     const isOwner = client.account && owner !== '(unknown)' && client.account.address.toLowerCase() === owner.toLowerCase();
@@ -63,7 +94,16 @@ export async function info(args) {
         console.log('  history starts: ', 'index', mn.firstAvailableIndex, '(earlier history truncated — see `compact`)');
     }
 
+    // Deliberately NOT `{ mustExist: true }` like every other command that reads a folder:
+    // `info` is a read-only report, and "you haven't pulled this anywhere yet" is a state
+    // worth describing rather than refusing over — the stream metadata above is already
+    // printed and still useful on its own.
     const destPath = resolvePath(args.path);
+    if (!folderExists(destPath)) {
+        console.log('\n  local folder:    missing (run `mnemonad pull` to fetch it)');
+        return;
+    }
+
     const localHash = await localTreeHash(destPath);
 
     if (!localHash) {

package/lib/commands/pull.js

@@ -8,16 +8,22 @@ import {
     syncMemoryFolderToDisk,
     writeManifest,
     unlockStream,
+    formatStreamId,
+    discoverStreamId,
 } from './shared.js';
 
 export async function pull(args) {
-    if (!args.streamId) {
-        throw new Error('stream-id is required for pull');
-    }
     // Resolved up front (throws if missing) so a missing path fails fast, before any chain
     // work — see resolvePath()'s own comment for why this is never defaulted to cwd.
     const destPath = resolvePath(args.path);
 
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, destPath);
+    if (!args.streamId) {
+        throw new Error('stream-id is required for pull');
+    }
+
     const client = makeChainClient(args);
 
     const mn = new Mnemonad({
@@ -35,7 +41,7 @@ export async function pull(args) {
     await unlockStream(mn, { password: args.password, signer: client.walletClient });
 
     const version = args.version != null ? Number(args.version) : undefined;
-    console.log('restoring', args.streamId, version != null ? 'at version ' + version : '(latest)', '...');
+    console.log('restoring', formatStreamId(args.streamId), version != null ? 'at version ' + version : '(latest)', '...');
 
     let folder;
     try {
@@ -56,7 +62,8 @@ export async function pull(args) {
     if (args.manifest) {
         await mn.initialize();
         const pulledVersion = version ?? mn.length;
-        await writeManifest(destPath, { streamId: args.streamId, version: pulledVersion, files: newFiles });
+        // Canonical form stored — see push.js's own writeManifest call for why.
+        await writeManifest(destPath, { streamId: formatStreamId(args.streamId), version: pulledVersion, files: newFiles });
     }
 
     console.log(' ', stats.written, 'written,', stats.skipped, 'unchanged,',

package/lib/commands/push.js

@@ -15,12 +15,20 @@ import {
     unlockStream,
     resolveEncryptMethod,
     resolveOffloadParams,
+    formatStreamId,
+    streamIdsEqual,
+    discoverStreamId,
 } from './shared.js';
 
 export async function push(args) {
+    const destPath = resolvePath(args.path, { mustExist: true });
+
+    // With --manifest and no id, a folder pushed before already has one recorded — reuse it
+    // rather than falling into the "no id" branch below and creating a second, unrelated
+    // stream for the same folder.
+    await discoverStreamId(args, destPath);
     let streamId = args.streamId;
 
-    const destPath = resolvePath(args.path);
     const fsFolder = new FSFolder(destPath, makeExcludes(args));
 
     const counts = await countTree(fsFolder);
@@ -29,7 +37,7 @@ export async function push(args) {
     if (args.manifest) {
         const manifest = await readManifest(destPath);
         const localFiles = await hashLocalTree(fsFolder);
-        if (streamId && manifest && manifest.streamId === streamId && manifest.files) {
+        if (streamId && manifest && streamIdsEqual(manifest.streamId, streamId) && manifest.files) {
             if (hashMapsEqual(localFiles, manifest.files)) {
                 console.log('  no changes since last pull, nothing to push');
                 return;
@@ -73,7 +81,7 @@ export async function push(args) {
         console.log('creating new stream on', args.chain, how, '...');
         mn = await Mnemonad.create(createParams);
         streamId = mn.id.toString();
-        console.log('  created:', streamId);
+        console.log('  created:', formatStreamId(streamId));
     } else {
         mn = new Mnemonad({ ...baseParams, id: streamId });
         await assertStreamOwner(mn, client.account.address);
@@ -83,7 +91,7 @@ export async function push(args) {
         }
     }
 
-    console.log('syncing ./ →', streamId);
+    console.log('syncing ./ →', formatStreamId(streamId));
 
     const monadSync = new MonadSync({ mnemonad: mn, compress: args.compress || 'gzip' });
 
@@ -118,10 +126,13 @@ export async function push(args) {
     const patchType = args.forceSnapshot || existingVersions === 0 ? 'full snapshot' : 'diff';
     const compressedNote = args.compress !== false ? ', gzip compressed' : '';
     console.log('  version', result.version, 'pushed (' + patchType + compressedNote + ')');
-    console.log('  stream:', streamId);
+    console.log('  stream:', formatStreamId(streamId));
 
     if (args.manifest) {
         const localFiles = await hashLocalTree(fsFolder);
-        await writeManifest(destPath, { streamId, version: result.version, files: localFiles });
+        // Stored canonical (see formatStreamId) rather than whatever form the caller typed —
+        // so a manifest written by a hex-id push and read back by a decimal-id one (or vice
+        // versa) still matches; streamIdsEqual() above is the belt to this suspenders.
+        await writeManifest(destPath, { streamId: formatStreamId(streamId), version: result.version, files: localFiles });
     }
 }

package/lib/commands/shared.js

@@ -1,4 +1,5 @@
 import { mkdir, writeFile, readFile, readdir, rm } from 'node:fs/promises';
+import { statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
@@ -56,15 +57,112 @@ export function resolveOffloadParams(args, account) {
  * `p` is missing — every command that touches a folder requires the caller to name it
  * explicitly, so a typo'd or omitted `path` never silently operates on whatever directory
  * the CLI happened to be run from.
+ *
+ * `mustExist` additionally requires the folder to be there already. Every command that
+ * *reads* the local folder passes it, because the alternative is worse than an error in
+ * both directions: `push`/`compact` used to surface a raw ENOENT stack trace from deep
+ * inside `readdir`, and `diff` used to treat a missing folder as an empty one and report
+ * every file in the stream as locally deleted — which reads as "your data is gone" rather
+ * than "you typed the wrong path". `pull` is the one command that leaves it off, since
+ * creating the destination is exactly its job.
+ *
+ * @param {?string} p
+ * @param {Object} [options]
+ * @param {boolean} [options.mustExist=false]
  */
-export function resolvePath(p) {
+export function resolvePath(p, { mustExist = false } = {}) {
     if (!p) {
-        const err = new Error('a folder path is required (e.g. `mnemonad <command> ... /path/to/folder`)');
-        err._isUserError = true;
-        throw err;
+        throw userError('a folder path is required (e.g. `mnemonad <command> ... /path/to/folder`)');
+    }
+
+    const resolved = p.startsWith('~') ? join(homedir(), p.slice(1)) : resolve(p);
+    if (!mustExist) return resolved;
+
+    const stat = statOrNull(resolved);
+    if (!stat) {
+        throw userError(
+            `no such folder: ${resolved}\n` +
+            '  Create it first, or use `mnemonad pull <stream-id> <path>` to fetch one into it.'
+        );
+    }
+    if (!stat.isDirectory()) {
+        throw userError(`not a folder: ${resolved}\n  This command syncs a directory, not a single file.`);
+    }
+    return resolved;
+}
+
+/** @returns {?import('node:fs').Stats} null when the path doesn't exist or isn't readable. */
+function statOrNull(path) {
+    try {
+        return statSync(path);
+    } catch {
+        return null;
     }
-    if (p.startsWith('~')) return join(homedir(), p.slice(1));
-    return resolve(p);
+}
+
+/** Whether `path` is an existing directory. For a command that reports on one rather than
+ *  refusing to run without it (see info.js). */
+export function folderExists(path) {
+    return statOrNull(path)?.isDirectory() === true;
+}
+
+/**
+ * Canonical display form for a stream id: `0x` + the full 32-byte token id, zero-padded,
+ * lowercase. Matches the dApp's own formatting (explorer/src/includes/formatStreamId.js),
+ * unelided — a CLI command needs the whole id to actually reuse, where the dApp's UI only
+ * needs enough of it to recognize at a glance.
+ *
+ * Takes whatever a stream id shows up as in this codebase — a bigint (`mn.id`), or a raw
+ * CLI arg that's either a decimal or a `0x`-hex string — since `BigInt()` parses all three
+ * natively; see bin/mnemonad.js's own `isStreamId` for why both string forms are accepted
+ * as input in the first place.
+ *
+ * @param {bigint|string} id
+ * @returns {string}
+ */
+export function formatStreamId(id) {
+    return '0x' + BigInt(id).toString(16).padStart(64, '0');
+}
+
+/**
+ * Whether two stream ids refer to the same token, regardless of which form either was
+ * written in (decimal, hex, differently-padded hex) — a plain `===` on the raw strings
+ * would wrongly call `123` and `0x7b` different streams.
+ */
+export function streamIdsEqual(a, b) {
+    if (a == null || b == null) return a === b;
+    return BigInt(a) === BigInt(b);
+}
+
+/** Networks a qualified stream id can name — see `parseQualifiedStreamId` below. Kept in
+ *  sync by hand with `chainClient.js`'s own `CHAINS` map (which also lists `local`, never
+ *  meaningful here — no URL is ever built with it) and with the explorer's
+ *  `src/settings.js` `NETWORKS` map, the source these prefixes actually come from. */
+export const NETWORK_PREFIXES = ['testnet', 'mainnet'];
+
+/**
+ * Splits the network-qualified stream-id form the explorer's URLs use — `<network>-0x<hex>`
+ * (or `<network>-<decimal>`), e.g. `testnet-0x648f18…` — into its network and bare id. Same
+ * split the explorer's own `streamRouteId()`/`parseStreamRouteId()`
+ * (`explorer/src/includes/streamRoute.js`) do, so an id copied straight out of a
+ * `/stream/<id>` link parses here too, instead of failing `BigInt()` on the whole string.
+ *
+ * Returns null for anything that isn't this exact shape — an unqualified id, a malformed
+ * one, or a prefix that isn't a known network (not a stream on some network this build
+ * hasn't heard of, just not this form).
+ *
+ * @param {string} s
+ * @returns {{network: string, id: string}|null}
+ */
+export function parseQualifiedStreamId(s) {
+    if (typeof s !== 'string') return null;
+    const dash = s.indexOf('-');
+    if (dash === -1) return null;
+    const prefix = s.slice(0, dash).toLowerCase();
+    if (!NETWORK_PREFIXES.includes(prefix)) return null;
+    const rest = s.slice(dash + 1);
+    if (!/^0x[0-9a-fA-F]+$/.test(rest) && !/^\d+$/.test(rest)) return null;
+    return { network: prefix, id: rest };
 }
 
 export function formatBytes(bytes) {
@@ -107,9 +205,10 @@ export async function assertStreamOwner(mn, signerAddress) {
     if (getAddress(owner) === getAddress(signerAddress)) return;
 
     const err = new Error(
-        `stream ${mn.id} is owned by ${owner}\n` +
+        `stream ${formatStreamId(mn.id)} is owned by ${owner}\n` +
         `  but you are signing as ${signerAddress}.\n` +
-        `  Nothing was uploaded. Use the owner's key (--key / --phrase / MNEMONAD_KEY),\n` +
+        `  Nothing was uploaded. Use the owner's key (--key, --phrase, or the MNEMONAD_KEY\n` +
+        `  env var, set to the private key),\n` +
         `  or run push without a stream id to create your own stream.`
     );
     err._isUserError = true;
@@ -199,7 +298,7 @@ export async function unlockStream(mn, credentials = {}) {
     if (!signer) {
         throw userError(
             'This stream is encrypted to its owner\'s wallet. Provide the owner\'s key with\n' +
-            '  --key / --phrase / MNEMONAD_KEY to decrypt it.'
+            '  --key, --phrase, or the MNEMONAD_KEY env var (set it to the private key) to decrypt it.'
         );
     }
     await mn.unlockWithSignature(signer);
@@ -244,6 +343,32 @@ export async function writeManifest(destPath, manifest) {
     await writeFile(join(destPath, '.mnemonad'), JSON.stringify(manifest, null, 2));
 }
 
+/**
+ * Recovers a stream id from the folder's own `.mnemonad` manifest when `--manifest` was
+ * passed and no id was given on the command line — the whole point of writing the manifest
+ * is that the id doesn't have to be remembered or re-typed for every later command on the
+ * same folder. Mutates `args.streamId` in place (every call site reads it back off `args`
+ * afterward) and is a no-op whenever an id was already given or `--manifest` wasn't passed —
+ * so it's safe to call unconditionally right after resolving the folder path.
+ *
+ * Silent when there's nothing to find (no `.mnemonad` yet, e.g. a folder's very first push,
+ * or a manifest with no `streamId`) — the caller's own "stream-id is required" error covers
+ * that case with the wording appropriate to its command.
+ *
+ * @param {Object} args - parsed CLI args, mutated in place
+ * @param {string} destPath - resolved folder path to look for `.mnemonad` in
+ * @returns {Promise<?string>} the resolved stream id, or whatever `args.streamId` already was
+ */
+export async function discoverStreamId(args, destPath) {
+    if (args.streamId || !args.manifest) return args.streamId;
+    const manifest = await readManifest(destPath);
+    if (manifest?.streamId) {
+        console.log('  using stream id from .mnemonad manifest:', formatStreamId(manifest.streamId));
+        args.streamId = manifest.streamId;
+    }
+    return args.streamId;
+}
+
 export const DISK_EXCLUDES = new Set(['.mnemonad', '.git', '.DS_Store', 'node_modules']);
 
 export async function hashDiskTree(dirPath, prefix = []) {

package/lib/commands/watch.js

@@ -14,6 +14,8 @@ import {
     assertStreamOwner,
     unlockStream,
     resolveOffloadParams,
+    formatStreamId,
+    discoverStreamId,
 } from './shared.js';
 
 function timestamp() {
@@ -27,9 +29,12 @@ function hashesEqual(a, b) {
 }
 
 export async function watch(args) {
-    if (!args.streamId) throw new Error('stream-id is required for watch');
+    const cwd = resolvePath(args.path, { mustExist: true });
 
-    const cwd = resolvePath(args.path);
+    // With --manifest and no id, a folder pulled/pushed before already has one recorded —
+    // no need to require it again.
+    await discoverStreamId(args, cwd);
+    if (!args.streamId) throw new Error('stream-id is required for watch');
     const debounceMs = args.debounce ?? 5000;
     const pollIntervalMs = (args.pollInterval ?? 2) * 1000;
     const pushEnabled = !args.pullOnly;
@@ -70,7 +75,7 @@ export async function watch(args) {
     let debounceTimer = null;
 
     console.log(`watching ${formatPath(cwd)}`);
-    console.log(`  stream:        ${args.streamId}`);
+    console.log(`  stream:        ${formatStreamId(args.streamId)}`);
     console.log(`  remote version: ${remoteVersion}`);
     console.log(`  push:          ${pushEnabled ? `enabled (debounce ${debounceMs}ms)` : 'disabled'}`);
     console.log(`  pull:          ${pullEnabled ? `enabled (poll every ${pollIntervalMs / 1000}s)` : 'disabled'}`);

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "mnemonad-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CLI to sync local folders to versioned, diffed on-chain streams on Monad, backed by Mnemonad + monadsync.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeka911/mnemonad.git",
+    "directory": "cli"
+  },
   "type": "module",
   "license": "AGPL-3.0",
   "bin": {