@arcadiasystems/morse-cli 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ All notable changes to `@arcadiasystems/morse-cli` are documented here. The
 format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-09-09
+
+Mainnet support, consuming `@arcadiasystems/morse-sdk@0.5.0`. The Move contracts
+went live on Sui mainnet on 2026-09-09; the CLI rejected `mainnet` outright until
+now.
+
+### Added
+
+- **`--network mainnet` works**, as do `MORSE_NETWORK=mainnet` and
+  `morse config add <name> --network mainnet`. `coerceNetwork` no longer
+  special-cases mainnet, and `localnet` is accepted too (it still fails at
+  startup unless you point the SDK at your own package and registry, which is
+  `morseConfig`'s error to raise, not the flag parser's).
+- **Commands that spend gas now name the network they spent on.** The resolved
+  network appears as the first detail line under the result headline, and as a
+  `network` field in `--json` output. Applied on the write contexts only, so read
+  and list output is byte-for-byte unchanged. Nothing selects mainnet implicitly
+  (with no flag, env var, or profile the CLI targets testnet), so this is there
+  to make a mainnet spend visible after the fact rather than to gate it.
+
+### Fixed
+
+- Status banner claimed v0.3.0, two releases stale, and said mainnet support was
+  pending.
+- `--network` help text listed only testnet and localnet, in both the global
+  flag (`morse --help`) and `config add --network`, as did the `MORSE_NETWORK`
+  row of the README env table.
+- Seven README links pointed into `examples/`, which is not in the package
+  `files` array, so they 404'd on the npm page. Now absolute GitHub URLs;
+  `docs/QUICKSTART.md` stays relative because `docs` does ship.
+- Dead Walrus faucet link in `docs/QUICKSTART.md`. `docs.walrus.site` no longer
+  resolves; WAL acquisition now points at the working stake-wal.wal.app swap,
+  matching the README and morse-sdk.
+- Known limitations now record that `file list` requires `--indexer-url`, since
+  public Sui fullnodes have retired the JSON-RPC event query it walks. This
+  affects testnet as well as mainnet and predates this release.
+
+### Known gaps
+
+- `file list` is unusable without `--indexer-url` on every network, per above.
+  Porting the event source off `suix_queryEvents` is tracked separately.
+- No mainnet run of the opt-in `bun run test:e2e` lifecycle; it stays pointed at
+  testnet, where it costs nothing real.
+- The Move contracts remain unaudited.
+
+## [0.5.0] - 2026-06-09
+
+Hardening pass from CLI testing: fail fast before paying for Walrus storage,
+clearer errors on doomed operations, and accurate listings.
+
+### Added
+
+- `revision publish-from-draft` now reuses the draft's already-uploaded content
+  by default (no re-upload, no extra WAL, and the published bytes match what was
+  reviewed). Pass `--file`/`--stdin` only to publish replacement content.
+- `entry list` / `entry scan` accept `--drafts-only` to show just entries with a
+  pending (unpublished) draft. `entry list`/`entry get` now show a draft marker /
+  `pendingDraft` line.
+- `file download --raw` writes the still-encrypted bytes when no decrypt input is
+  given.
+
+### Changed
+
+- `file download` now refuses to write ciphertext when a file has recipients and
+  no `--share`/`--prefix`+`--nonce` is given; pass `--raw` to opt in. Previously
+  it warned and wrote the raw bytes.
+- `entry add` verifies the collection exists (and is blob-mode) before uploading
+  to Walrus, so a missing or quilt collection fails without burning storage.
+- `collection delete` checks the collection is empty up front and returns a clear
+  error instead of a raw transaction abort.
+- `file list` now reconciles metadata-update and recipient events, so renames and
+  recipient counts are current without `--hydrate`.
+- `collection create --mode quilt` warns that quilt collections cannot yet be
+  populated with `entry add`.
+
+### Fixed
+
+- The `revision` commands refuse to append an unencrypted revision to an entry
+  that has encrypted revisions, instead of silently producing a mixed-encryption
+  entry.
+
 ## [0.4.2] - 2026-06-05
 
 ### Changed

package/README.md

@@ -6,16 +6,24 @@ content entries from your terminal, signing with a locally encrypted key.
 Content is stored on [Walrus](https://walrus.xyz); private entries are encrypted
 with [Seal](https://github.com/MystenLabs/seal).
 
-> Status: v0.3.0, targeting Sui testnet. The command surface is stable; mainnet
-> support lands when the contracts are frozen.
+> Status: v0.6.0. Mainnet and testnet are both supported; the command surface is
+> stable.
+>
+> **The Move contracts are unaudited.** On mainnet, gas and Walrus storage cost
+> real SUI and WAL, there is no faucet, and deletions are irreversible. Nothing
+> selects mainnet for you: with no `--network`, `MORSE_NETWORK`, or profile
+> setting, the CLI targets testnet. Every command that spends gas prints the
+> network it used, and `--json` output carries a `network` field.
 
 ## Requirements
 
 - [Node.js](https://nodejs.org) >= 18, or [Bun](https://bun.sh) >= 1.2. The
   published CLI runs under either.
-- A funded Sui testnet address for gas, and testnet WAL for Walrus storage when
-  adding content. Get SUI from the [Sui faucet](https://faucet.sui.io/) and WAL
-  from the [Walrus testnet faucet](https://docs.walrus.site/usage/web-tool.html).
+- A funded Sui address for gas, and WAL for Walrus storage when adding content.
+  On testnet, get SUI from the [Sui faucet](https://faucet.sui.io/) and swap some
+  for WAL at [stake-wal.wal.app](https://stake-wal.wal.app/?network=testnet). On
+  mainnet there is no faucet: both have to be acquired, and every write spends
+  real value.
 
 ## Install
 
@@ -91,7 +99,7 @@ Environment variables (override the config file, overridden by flags):
 | Variable | Overrides | Notes |
 | --- | --- | --- |
 | `MORSE_PROFILE` | `--profile` | Profile to use. |
-| `MORSE_NETWORK` | `--network` | `testnet` or `localnet`. |
+| `MORSE_NETWORK` | `--network` | `mainnet`, `testnet`, or `localnet`. |
 | `MORSE_RPC_URL` | `--rpc` | Sui RPC URL override. |
 | `MORSE_ADDRESS` | (no flag) | Active account address, selecting which keystore to use. |
 | `MORSE_PUBLICATION` | `-P, --publication` | Active publication id. |
@@ -123,7 +131,7 @@ Global options apply to every command and must appear before the subcommand
 
 | Global option | Purpose |
 | --- | --- |
-| `--network <testnet\|localnet>` | Network to target (default: testnet). |
+| `--network <mainnet\|testnet\|localnet>` | Network to target (default: testnet). `localnet` needs a custom deployment. |
 | `-p, --profile <name>` | Config profile to use. |
 | `--rpc <url>` | Override the Sui RPC URL. |
 | `--json` | Machine-readable JSON on stdout. |
@@ -188,8 +196,8 @@ and `-C, --collection <name>`, both defaulting to the active context.
 | --- | --- |
 | `entry get <entryId> [-P …] [-C …]` | Fetch a single entry's metadata. |
 | `entry read <entryId> [revisionIndex] [--out <path>] [--via-aggregator] [-P …] [-C …]` | Fetch a public entry's content to stdout or a file. |
-| `entry list [-P …] [-C …]` | List entries (paginated). |
-| `entry scan [-P …] [-C …]` | List every entry (auto-paginated). |
+| `entry list [--drafts-only] [-P …] [-C …]` | List entries (paginated); `--drafts-only` shows just entries with a pending draft. |
+| `entry scan [--drafts-only] [-P …] [-C …]` | List every entry (auto-paginated). |
 | `entry add <name> --file <path> [-P …] [-C …]` | Upload content and add a new entry; prints a viewable link. |
 | `entry delete <entryId> [-P …] [-C …]` | Delete an entry. |
 | `entry add-encrypted <name> --file <path> [-P …] [-C …]` | Encrypt, upload, and add a new entry. |
@@ -212,7 +220,7 @@ commands; pure on-chain commands (publication, collection, cap) have no epochs.
 | --- | --- |
 | `revision publish-direct <entryId> --file <path> [-P …] [-C …]` | Upload content and append a public revision. |
 | `revision append-draft <entryId> --file <path> [-P …] [-C …]` | Upload content and append a draft revision. |
-| `revision publish-from-draft <entryId> <draftRevisionId> --file <path> [-P …] [-C …]` | Publish a new revision, referencing a draft. |
+| `revision publish-from-draft <entryId> <draftRevisionId> [--file <path>] [-P …] [-C …]` | Publish a draft as a new revision. Reuses the draft's content by default; pass `--file`/`--stdin` to publish replacement content. |
 
 ### cap
 
@@ -238,7 +246,7 @@ There is no separate allowlist object.
 | --- | --- |
 | `file upload <path> --name <n> (--public \| --encrypt \| -r <addr>...) [--content-type <m>] [--epochs <n>]` | Upload to Walrus and register. `--public` is world-readable; `--encrypt` (or supplying `-r`) encrypts, and the sender is always a recipient. One of the three is required. |
 | `file register --blob-id <id> --name <n> --content-type <m> --size <bytes> (--public \| --encrypted --seal-prefix <hex>) [-r <addr>...] [--blob-object-id <id>]` | Register metadata for a blob already on Walrus. |
-| `file download [file] [--out <path>] [--share <s>] [--prefix <hex> --nonce <hex>] [--via-aggregator]` | Download content; decrypts in place with a share string (or prefix + nonce). |
+| `file download [file] [--out <path>] [--share <s>] [--prefix <hex> --nonce <hex>] [--raw] [--via-aggregator]` | Download content; decrypts in place with a share string (or prefix + nonce). For an encrypted file with no decrypt input, it refuses unless `--raw` is given. |
 | `file list [--address <addr>] [--accessible] [--hydrate] [--limit <n>] [--indexer-url <url>]` | List files owned by (or, with `--accessible`, decryptable by) an address. |
 | `file get <file>` | Fetch a file's on-chain metadata and recipient list. |
 | `file update <file> --name <n> --content-type <m>` | Update name and MIME (owner only). |
@@ -290,13 +298,13 @@ to fetch the full record per file (one read each) when you need them.
 ## Examples
 
 - [docs/QUICKSTART.md](./docs/QUICKSTART.md): a full, copy-pasteable walkthrough.
-- Runnable shell recipes in [examples/](./examples/):
-  - [`lifecycle.sh`](./examples/lifecycle.sh): create, add an entry, read, revise, tear down.
-  - [`content.sh`](./examples/content.sh): upload an image and a post, publish a revision, fetch content back, get a link, remove a collection.
-  - [`encrypt-decrypt.sh`](./examples/encrypt-decrypt.sh): encrypt with Seal and decrypt back.
-  - [`delegation.sh`](./examples/delegation.sh): issue a PublisherCap to a delegate, then revoke it.
-  - [`ci-noninteractive.sh`](./examples/ci-noninteractive.sh): env-var auth, `--yes`, and `--json` parsing.
-  - [`files.sh`](./examples/files.sh): RecipientFile round-trip (upload an encrypted file, download/decrypt via its share string, manage recipients, plus a public file).
+- Runnable shell recipes in [examples/](https://github.com/arcadiasystems/morse-dcms/tree/main/morse-cli/examples):
+  - [`lifecycle.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/lifecycle.sh): create, add an entry, read, revise, tear down.
+  - [`content.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/content.sh): upload an image and a post, publish a revision, fetch content back, get a link, remove a collection.
+  - [`encrypt-decrypt.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/encrypt-decrypt.sh): encrypt with Seal and decrypt back.
+  - [`delegation.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/delegation.sh): issue a PublisherCap to a delegate, then revoke it.
+  - [`ci-noninteractive.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/ci-noninteractive.sh): env-var auth, `--yes`, and `--json` parsing.
+  - [`files.sh`](https://github.com/arcadiasystems/morse-dcms/blob/main/morse-cli/examples/files.sh): RecipientFile round-trip (upload an encrypted file, download/decrypt via its share string, manage recipients, plus a public file).
 
 ## Limitations
 
@@ -311,7 +319,19 @@ to fetch the full record per file (one read each) when you need them.
   to read through the Walrus aggregator HTTP service instead: more reliable when
   storage nodes are flaky (common on testnet), at the cost of trusting the
   aggregator's bytes (no client-side verification).
-- Mainnet is not yet deployed; use `testnet`.
+- Encrypted entries cannot be revised. The `revision` commands and `entry add`
+  only produce unencrypted content, so the CLI refuses to append to an entry that
+  already has encrypted revisions (to avoid a mixed-encryption entry). Use
+  `entry add-encrypted` for new encrypted entries.
+- `entry add` supports blob-mode collections only. Quilt collections can be
+  created but not yet populated through the CLI; `entry add` refuses them.
+- There is no command to query Walrus blob storage expiry; `--epochs` sets the
+  lease at upload time, but remaining lease time is not exposed by the SDK.
+- `localnet` is accepted as a network but has no canonical deployment, so it
+  fails at startup unless you point the SDK at your own package and registry.
+- `file list` walks a JSON-RPC event query that public Sui fullnodes have
+  retired, so it needs `--indexer-url` pointing at a source that serves the same
+  query. This affects testnet as well as mainnet.
 
 ## Publishing
 

package/dist/index.js

@@ -148,7 +148,7 @@ import { Command } from "commander";
 // package.json
 var package_default = {
   name: "@arcadiasystems/morse-cli",
-  version: "0.4.2",
+  version: "0.6.0",
   description: "Command-line interface for the Morse decentralized CMS on Sui.",
   license: "MIT",
   type: "module",
@@ -203,7 +203,7 @@ var package_default = {
     prepublishOnly: "bun run check && bun run build"
   },
   dependencies: {
-    "@arcadiasystems/morse-sdk": "^0.4.2",
+    "@arcadiasystems/morse-sdk": "^0.5.0",
     "@mysten/seal": "1.1.3",
     "@mysten/sui": "2.16.2",
     "@mysten/walrus": "1.1.6",
@@ -219,7 +219,7 @@ var package_default = {
 // src/cli/program.ts
 function buildProgram() {
   const program = new Command;
-  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: testnet or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
+  program.name("morse").description("Command-line interface for the Morse decentralized CMS on Sui.").version(package_default.version, "-V, --version", "Print the version and exit").option("--network <network>", "Sui network: mainnet, testnet, or localnet [env: MORSE_NETWORK]").option("-p, --profile <name>", "Config profile to use [env: MORSE_PROFILE]").option("--rpc <url>", "Override the Sui RPC URL [env: MORSE_RPC_URL]").option("--json", "Output machine-readable JSON on stdout").option("-q, --quiet", "Suppress progress and informational output").option("-y, --yes", "Assume yes for confirmation prompts").option("--debug", "Print stack traces on error").enablePositionalOptions().showHelpAfterError().exitOverride();
   return program;
 }
 
@@ -316,14 +316,39 @@ class Output {
   get isJson() {
     return this.options.json;
   }
+  withNetwork(network) {
+    return new Output({ ...this.options, network });
+  }
   result(human, data) {
     if (this.options.json) {
-      this.out(`${toJson(data)}
+      this.out(`${toJson(this.stampJson(data))}
 `);
       return;
     }
-    this.out(`${human}
+    this.out(`${this.stampHuman(human)}
+`);
+  }
+  stampJson(data) {
+    const network = this.options.network;
+    if (network === undefined || !isPlainObject(data) || "network" in data) {
+      return data;
+    }
+    return { network, ...data };
+  }
+  stampHuman(human) {
+    const network = this.options.network;
+    if (network === undefined) {
+      return human;
+    }
+    const line = `  network:      ${network}`;
+    const breakAt = human.indexOf(`
 `);
+    if (breakAt === -1) {
+      return `${human}
+${line}`;
+    }
+    return `${human.slice(0, breakAt)}
+${line}${human.slice(breakAt)}`;
   }
   info(message) {
     if (this.options.quiet || this.options.json) {
@@ -369,6 +394,9 @@ function resolveColor(json) {
   }
   return Boolean(process.stderr.isTTY);
 }
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function createOutput(opts) {
   const json = Boolean(opts.json);
   return new Output({
@@ -397,13 +425,10 @@ function isNetwork(value) {
   return typeof value === "string" && NETWORKS.has(value);
 }
 function coerceNetwork(value) {
-  if (value === Network.Mainnet) {
-    throw new UsageError("Morse is not yet deployed on mainnet. Use testnet or localnet.");
-  }
   if (isNetwork(value)) {
     return value;
   }
-  throw new UsageError(`Unknown network "${value}". Use one of: testnet, localnet.`);
+  throw new UsageError(`Unknown network "${value}". Use one of: mainnet, testnet, localnet.`);
 }
 function parseConfig(raw, source) {
   if (!isRecord(raw)) {
@@ -945,6 +970,7 @@ async function buildWriteContext(command) {
   const { base, keypair, address } = await buildSignedBase(command);
   return {
     ...base,
+    output: base.output.withNetwork(base.settings.network),
     adapter: new KeypairAdapter(keypair, base.client),
     address
   };
@@ -966,7 +992,13 @@ async function buildContentContext(command) {
   }
   const adapter = new KeypairAdapter(keypair, base.client);
   const walrus = DefaultWalrusWriteAdapter.fromConfig({ network, suiClient: base.client }, keypair);
-  return { ...base, adapter, address, walrus };
+  return {
+    ...base,
+    output: base.output.withNetwork(network),
+    adapter,
+    address,
+    walrus
+  };
 }
 async function buildEncryptContext(command) {
   const ctx = await buildContentContext(command);
@@ -1136,11 +1168,18 @@ function renderPublicationList(items) {
   return items.map((item) => `${item.publicationId}  (owner cap ${shortId(item.ownerCapId)})`).join(`
 `);
 }
+function hasPendingDraft(entry) {
+  if (entry.draftHead === null) {
+    return false;
+  }
+  return entry.publicHead === null || entry.draftHead > entry.publicHead;
+}
 function renderEntry(entry) {
   const lines = [
     `#${entry.id} ${entry.name}`,
-    `publicHead: ${headLabel(entry.publicHead)}  draftHead: ${headLabel(entry.draftHead)}`,
-    `revisions:  ${entry.revisions.length}`
+    `publicHead:   ${headLabel(entry.publicHead)}  draftHead: ${headLabel(entry.draftHead)}`,
+    `pendingDraft: ${hasPendingDraft(entry) ? "yes" : "no"}`,
+    `revisions:    ${entry.revisions.length}`
   ];
   for (const revision of entry.revisions) {
     lines.push(`  ${renderRevisionLine(revision)}`);
@@ -1152,7 +1191,10 @@ function renderEntryList(entries) {
   if (entries.length === 0) {
     return "No entries in this collection.";
   }
-  return entries.map((entry) => `#${entry.id} ${entry.name} (${entry.revisions.length} revisions)`).join(`
+  return entries.map((entry) => {
+    const marker = hasPendingDraft(entry) ? " [draft]" : "";
+    return `#${entry.id} ${entry.name} (${entry.revisions.length} revisions)${marker}`;
+  }).join(`
 `);
 }
 function renderFileList(items) {
@@ -1397,7 +1439,11 @@ function registerCapCommands(program) {
 }
 
 // src/commands/collection.ts
-import { createCollection, deleteCollection } from "@arcadiasystems/morse-sdk";
+import {
+  createCollection,
+  deleteCollection,
+  StorageMode as StorageMode2
+} from "@arcadiasystems/morse-sdk";
 async function runCollectionList(ctx, options) {
   const id = await resolvePublication(ctx, options.publication);
   const publication = await ctx.reader.getPublication(id, ctx.signal);
@@ -1410,6 +1456,9 @@ async function runCollectionCreate(ctx, name, options, gopts) {
   const id = await resolvePublication(ctx, options.publication);
   const storageMode = coerceStorageMode(options.mode);
   const publisherCapId = await resolvePublisherCap(ctx.reader, ctx.address, id, options.publisherCap, ctx.signal);
+  if (storageMode === StorageMode2.Quilt) {
+    ctx.output.warn("Quilt collections cannot yet be populated with `morse entry add` (only blob collections are supported).");
+  }
   ctx.output.info(`Creating collection "${name}" (${storageMode})...`);
   const result = await createCollection(ctx.adapter, ctx.config, {
     publicationId: id,
@@ -1423,6 +1472,13 @@ async function runCollectionCreate(ctx, name, options, gopts) {
 }
 async function runCollectionDelete(ctx, name, options, gopts) {
   const id = await resolvePublication(ctx, options.publication);
+  const entries = await ctx.reader.listEntries(id, name, {
+    limit: 1,
+    signal: ctx.signal
+  });
+  if (entries.results.length > 0) {
+    throw new UsageError(`Cannot delete collection "${name}": it still has entries. Delete them first.`);
+  }
   const proceed = await confirm(`Delete collection "${name}" from ${shortId(id)}? It must be empty.`, { assumeYes: Boolean(gopts.yes), signal: ctx.signal });
   if (!proceed) {
     cancelled();
@@ -1512,7 +1568,7 @@ function registerConfigCommands(program) {
   config.command("list").description("List profiles and show the default").action(async (_options, command) => {
     await runConfigList(outputFor(command));
   });
-  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: testnet or localnet").option("--rpc <url>", "RPC URL override for this profile").action(async (name, options, command) => {
+  config.command("add <name>").description("Create or update a profile").requiredOption("--network <network>", "Sui network: mainnet, testnet, or localnet").option("--rpc <url>", "RPC URL override for this profile").action(async (name, options, command) => {
     await runConfigAdd(outputFor(command), name, options);
   });
   config.command("use <name>").description("Set the default profile").action(async (name, _options, command) => {
@@ -1553,7 +1609,8 @@ function renderProfiles(config) {
 // src/commands/entry.ts
 import {
   addEntryFromBytes,
-  deleteEntry
+  deleteEntry,
+  StorageMode as StorageMode3
 } from "@arcadiasystems/morse-sdk";
 
 // src/cli/input.ts
@@ -1701,6 +1758,16 @@ function registerEncryptedEntryCommands(entry) {
 }
 
 // src/commands/entry.ts
+async function assertEntryAddCollection(ctx, publicationId, collection) {
+  const publication = await ctx.reader.getPublication(publicationId, ctx.signal);
+  const found = publication.collections.find((c) => c.name === collection);
+  if (found === undefined) {
+    throw new UsageError(`Publication ${shortId(publicationId)} has no collection "${collection}".`);
+  }
+  if (found.storageMode === StorageMode3.Quilt) {
+    throw new UsageError(`Collection "${collection}" uses quilt storage, which \`entry add\` does not support yet. Use a blob-mode collection.`);
+  }
+}
 async function runEntryGet(ctx, entryId, options) {
   const id = await resolvePublication(ctx, options.publication);
   const collection = resolveCollection(ctx, options.collection);
@@ -1718,8 +1785,9 @@ async function runEntryList(ctx, options) {
   if (page.nextCursor !== null) {
     ctx.output.info(`More results: pass --cursor "${page.nextCursor}"`);
   }
-  ctx.output.result(renderEntryList(page.results), {
-    results: page.results,
+  const results = options.draftsOnly ? page.results.filter(hasPendingDraft) : page.results;
+  ctx.output.result(renderEntryList(results), {
+    results,
     nextCursor: page.nextCursor
   });
 }
@@ -1730,7 +1798,9 @@ async function runEntryScan(ctx, options) {
   for await (const item of ctx.reader.scanEntries(id, collection, {
     signal: ctx.signal
   })) {
-    entries.push(item);
+    if (!options.draftsOnly || hasPendingDraft(item)) {
+      entries.push(item);
+    }
   }
   ctx.output.result(renderEntryList(entries), { results: entries });
 }
@@ -1740,6 +1810,7 @@ async function runEntryAdd(ctx, name, options) {
   const epochs = parsePositiveInt(options.epochs, "--epochs");
   const bytes = await readContentBytes(options);
   const contentType = resolveContentType(options.contentType, options.stdin ? undefined : options.file);
+  await assertEntryAddCollection(ctx, id, collection);
   const publisherCapId = await resolvePublisherCap(ctx.reader, ctx.address, id, options.publisherCap, ctx.signal);
   ctx.output.info(`Uploading ${bytes.length} bytes to Walrus...`);
   const result = await addEntryFromBytes(ctx.adapter, ctx.config, {
@@ -1819,11 +1890,11 @@ function registerEntryCommands(program) {
   collectionOption(publicationOption(get)).action(async (entryId, options, command) => {
     await runEntryGet(await buildReadContext(command), entryId, options);
   });
-  const list = entry.command("list").description("List entries in a collection").option("--limit <n>", "Maximum results per page").option("--cursor <cursor>", "Continue from a previous page cursor");
+  const list = entry.command("list").description("List entries in a collection").option("--limit <n>", "Maximum results per page").option("--cursor <cursor>", "Continue from a previous page cursor").option("--drafts-only", "Show only entries with a pending (unpublished) draft");
   collectionOption(publicationOption(list)).action(async (options, command) => {
     await runEntryList(await buildReadContext(command), options);
   });
-  const scan = entry.command("scan").description("List every entry in a collection (auto-paginated)");
+  const scan = entry.command("scan").description("List every entry in a collection (auto-paginated)").option("--drafts-only", "Show only entries with a pending (unpublished) draft");
   collectionOption(publicationOption(scan)).action(async (options, command) => {
     await runEntryScan(await buildReadContext(command), options);
   });
@@ -2078,7 +2149,7 @@ async function runFileUpload(ctx, path, options) {
   const upload = { epochs, deletable: true };
   const onProgress = uploadProgress(ctx.output);
   if (options.public) {
-    const result2 = await uploadRecipientFileFromBytes(ctx.adapter, ctx.config, {
+    const result = await uploadRecipientFileFromBytes(ctx.adapter, ctx.config, {
       walrus: ctx.walrus,
       bytes,
       recipients: [],
@@ -2089,10 +2160,10 @@ async function runFileUpload(ctx, path, options) {
       onProgress
     });
     const aggregator = ctx.config.walrusEndpoints.aggregator;
-    const viewUrl = aggregator.length > 0 ? `${aggregator}/v1/blobs/${result2.blobId}` : undefined;
-    const human2 = viewUrl === undefined ? `Uploaded public file ${result2.fileId}. (tx: ${result2.digest})` : `Uploaded public file ${result2.fileId}. (tx: ${result2.digest})
+    const viewUrl = aggregator.length > 0 ? `${aggregator}/v1/blobs/${result.blobId}` : undefined;
+    const human = viewUrl === undefined ? `Uploaded public file ${result.fileId}. (tx: ${result.digest})` : `Uploaded public file ${result.fileId}. (tx: ${result.digest})
   view: ${viewUrl}`;
-    ctx.output.result(human2, { ...result2, viewUrl: viewUrl ?? null });
+    ctx.output.result(human, { ...result, viewUrl: viewUrl ?? null });
     return;
   }
   const result = await uploadEncryptedRecipientFileFromBytes(ctx.adapter, ctx.config, {
@@ -2178,10 +2249,16 @@ async function runFileDownload(ctx, positional, options) {
     throw new UsageError("Downloading content to stdout is not supported in --json mode; pass --out <path>.");
   }
   const target = resolveDownloadTarget(positional, options);
+  if (options.raw && target.decrypt !== undefined) {
+    ctx.output.warn("--raw is ignored because a decrypt input (--share/--prefix/--nonce) was given; decrypting.");
+  }
   const fileId = toRecipientFileId(target.fileId);
   const file = await ctx.filesReader.getRecipientFile(fileId, ctx.signal);
   if (target.decrypt === undefined && file.members.length > 0) {
-    ctx.output.warn("This file has a recipient list, so its bytes are likely encrypted. Pass --share (or --prefix and --nonce) to decrypt; writing the raw bytes as-is.");
+    if (!options.raw) {
+      throw new UsageError("This file has a recipient list, so its bytes are encrypted. Pass --share (or --prefix and --nonce) to decrypt, or --raw to write the raw ciphertext anyway.");
+    }
+    ctx.output.warn("Writing raw ciphertext (--raw); the output is unusable without decryption.");
   }
   ctx.output.info("Fetching content from Walrus...");
   const bytes = await ctx.walrusRead.readBlob(file.blobId, {
@@ -2216,6 +2293,7 @@ async function runFileList(ctx, options) {
     ctx.output.info("Fetching recipient and file events...");
     const events = await fetchEventStreams(ctx.events, [
       types.RecipientFileCreated,
+      types.RecipientFileMetadataUpdated,
       types.RecipientAdded,
       types.RecipientRemoved,
       types.RecipientFileDeleted
@@ -2225,7 +2303,10 @@ async function runFileList(ctx, options) {
     ctx.output.info("Fetching file events...");
     const events = await fetchEventStreams(ctx.events, [
       types.RecipientFileCreated,
+      types.RecipientFileMetadataUpdated,
       types.RecipientFileOwnershipTransferred,
+      types.RecipientAdded,
+      types.RecipientRemoved,
       types.RecipientFileDeleted
     ], ctx.signal);
     summaries = reconcileRecipientFilesOwnedBy(events, address, types);
@@ -2254,7 +2335,7 @@ function registerFileCommands(program) {
       indexerUrl: options.indexerUrl
     }), options);
   });
-  const download = file.command("download [file]").description("Download a file's content; decrypts in place when encrypted").option("--out <path>", "Write content to a file instead of stdout").option("--share <string>", "Share string from upload (bundles file id, prefix, nonce)").option("--prefix <hex>", "Seal prefix (with --nonce) to decrypt").option("--nonce <hex>", "Seal nonce (with --prefix) to decrypt");
+  const download = file.command("download [file]").description("Download a file's content; decrypts in place when encrypted").option("--out <path>", "Write content to a file instead of stdout").option("--share <string>", "Share string from upload (bundles file id, prefix, nonce)").option("--prefix <hex>", "Seal prefix (with --nonce) to decrypt").option("--nonce <hex>", "Seal nonce (with --prefix) to decrypt").option("--raw", "Write the raw (still-encrypted) bytes when no decrypt input is given");
   viaAggregatorOption(download).action(async (target, options, command) => {
     await runFileDownload(await buildFileDownloadContext(command, {
       viaAggregator: options.viaAggregator
@@ -2428,26 +2509,41 @@ async function resolveTarget(ctx, options) {
   const collection = resolveCollection(ctx, options.collection);
   return { publicationId, collection };
 }
-async function prepareContent(ctx, publicationId, options) {
+async function loadWritableEntry(ctx, publicationId, collection, entryId) {
+  const entry = await ctx.reader.getEntry(publicationId, collection, entryId, ctx.signal);
+  if (entry.revisions.some((revision) => revision.encrypted)) {
+    throw new UsageError(`Entry #${entryId} has encrypted revisions; the CLI cannot append an unencrypted revision to it. Encrypted revisions are not yet supported.`);
+  }
+  return entry;
+}
+async function readLocalContent(options) {
   const epochs = parsePositiveInt(options.epochs, "--epochs");
   const bytes = await readContentBytes(options);
   const contentType = resolveContentType(options.contentType, options.stdin ? undefined : options.file);
-  const publisherCapId = await resolvePublisherCap(ctx.reader, ctx.address, publicationId, options.publisherCap, ctx.signal);
-  ctx.output.info(`Uploading ${bytes.length} bytes to Walrus...`);
-  const upload = await ctx.walrus.uploadBlob(bytes, {
-    epochs,
+  return { bytes, contentType, epochs };
+}
+async function uploadLocal(ctx, local) {
+  ctx.output.info(`Uploading ${local.bytes.length} bytes to Walrus...`);
+  const upload = await ctx.walrus.uploadBlob(local.bytes, {
+    epochs: local.epochs,
     deletable: true
   });
   ctx.output.info(`Blob uploaded (${upload.blobObjectId}). Submitting transaction...`);
-  return { blobObjectId: upload.blobObjectId, contentType, publisherCapId };
+  return { blobObjectId: upload.blobObjectId, contentType: local.contentType };
+}
+function capFor(ctx, publicationId, options) {
+  return resolvePublisherCap(ctx.reader, ctx.address, publicationId, options.publisherCap, ctx.signal);
 }
 async function runRevisionPublishDirect(ctx, entryId, options) {
   const { publicationId, collection } = await resolveTarget(ctx, options);
   const numericEntryId = parseId(entryId, "entryId");
-  const prepared = await prepareContent(ctx, publicationId, options);
+  const local = await readLocalContent(options);
+  await loadWritableEntry(ctx, publicationId, collection, numericEntryId);
+  const publisherCapId = await capFor(ctx, publicationId, options);
+  const prepared = await uploadLocal(ctx, local);
   const result = await publishDirect(ctx.adapter, ctx.config, {
     publicationId,
-    publisherCapId: prepared.publisherCapId,
+    publisherCapId,
     collectionName: collection,
     entryId: numericEntryId,
     blobObjectId: prepared.blobObjectId,
@@ -2459,10 +2555,13 @@ async function runRevisionPublishDirect(ctx, entryId, options) {
 async function runRevisionAppendDraft(ctx, entryId, options) {
   const { publicationId, collection } = await resolveTarget(ctx, options);
   const numericEntryId = parseId(entryId, "entryId");
-  const prepared = await prepareContent(ctx, publicationId, options);
+  const local = await readLocalContent(options);
+  await loadWritableEntry(ctx, publicationId, collection, numericEntryId);
+  const publisherCapId = await capFor(ctx, publicationId, options);
+  const prepared = await uploadLocal(ctx, local);
   const result = await appendDraftRevision(ctx.adapter, ctx.config, {
     publicationId,
-    publisherCapId: prepared.publisherCapId,
+    publisherCapId,
     collectionName: collection,
     entryId: numericEntryId,
     blobObjectId: prepared.blobObjectId,
@@ -2471,14 +2570,31 @@ async function runRevisionAppendDraft(ctx, entryId, options) {
   });
   ctx.output.result(`Appended draft revision #${result.revisionId} on entry #${numericEntryId}. (tx: ${result.digest})`, result);
 }
+function reuseDraftBlob(entry, draftRevisionId) {
+  const draft = entry.revisions.find((r) => r.id === draftRevisionId);
+  if (draft === undefined) {
+    throw new UsageError(`Entry #${entry.id} has no revision #${draftRevisionId} to publish.`);
+  }
+  if (draft.blobRef.kind !== "blob") {
+    throw new UsageError(`Draft #${draftRevisionId} uses quilt storage, which cannot be reused; pass --file or --stdin to publish new content.`);
+  }
+  return {
+    blobObjectId: draft.blobRef.blobObjectId,
+    contentType: draft.contentType
+  };
+}
 async function runRevisionPublishFromDraft(ctx, entryId, draftRevisionId, options) {
   const { publicationId, collection } = await resolveTarget(ctx, options);
   const numericEntryId = parseId(entryId, "entryId");
   const draftId = parseId(draftRevisionId, "draftRevisionId");
-  const prepared = await prepareContent(ctx, publicationId, options);
+  const providedNewContent = options.file !== undefined || Boolean(options.stdin);
+  const local = providedNewContent ? await readLocalContent(options) : undefined;
+  const entry = await loadWritableEntry(ctx, publicationId, collection, numericEntryId);
+  const publisherCapId = await capFor(ctx, publicationId, options);
+  const prepared = local === undefined ? reuseDraftBlob(entry, draftId) : await uploadLocal(ctx, local);
   const result = await publishFromDraft(ctx.adapter, ctx.config, {
     publicationId,
-    publisherCapId: prepared.publisherCapId,
+    publisherCapId,
     collectionName: collection,
     entryId: numericEntryId,
     draftRevisionId: draftId,
@@ -2496,7 +2612,7 @@ function registerRevisionCommands(program) {
   revisionOptions(revision.command("append-draft <entryId>").description("Upload content and append it as a draft revision")).action(async (entryId, options, command) => {
     await runRevisionAppendDraft(await buildContentContext(command), entryId, options);
   });
-  revisionOptions(revision.command("publish-from-draft <entryId> <draftRevisionId>").description("Upload content and publish it as a new revision, referencing a draft")).action(async (entryId, draftRevisionId, options, command) => {
+  revisionOptions(revision.command("publish-from-draft <entryId> <draftRevisionId>").description("Publish a draft as a new revision (reuses the draft's content; pass --file/--stdin to publish replacement content)")).action(async (entryId, draftRevisionId, options, command) => {
     await runRevisionPublishFromDraft(await buildContentContext(command), entryId, draftRevisionId, options);
   });
 }
@@ -2504,11 +2620,11 @@ function registerRevisionCommands(program) {
 // src/commands/use.ts
 async function runUse(output, gopts, publication, collection, options, makeContext) {
   if (options.clear) {
-    const profile2 = await updateActiveProfile(gopts, {
+    const profile = await updateActiveProfile(gopts, {
       publication: undefined,
       collection: undefined
     });
-    output.result(`Cleared the active publication and collection (profile "${profile2}").`, { profile: profile2, publication: null, collection: null });
+    output.result(`Cleared the active publication and collection (profile "${profile}").`, { profile, publication: null, collection: null });
     return;
   }
   if (publication === undefined) {

package/docs/QUICKSTART.md

@@ -5,14 +5,21 @@ Sui testnet, then tears it down. Every command is copy-pasteable; expected
 output is shown beneath each step. Replace IDs in later steps with the ones your
 own runs print.
 
+The walkthrough uses testnet on purpose: it creates a publication, uploads
+content to Walrus, and deletes it all again. On mainnet that sequence costs real
+SUI and WAL. Once it works for you, the only change needed is the network on the
+profile in step 1 (`--network mainnet`); every later command reads the network
+from the profile and prints which one it spent on.
+
 ## 0. Prerequisites
 
 - Install [Bun](https://bun.sh) >= 1.2.
 - Have a Sui testnet keypair. If you use the Sui CLI, export one with
   `sui keytool export --key-identity <alias>` to get a `suiprivkey1...` string.
 - Fund the address with testnet SUI ([faucet](https://faucet.sui.io/)) for gas,
-  and with WAL ([Walrus faucet](https://docs.walrus.site/usage/web-tool.html))
-  for content uploads.
+  and with WAL by swapping some SUI at
+  [stake-wal.wal.app](https://stake-wal.wal.app/?network=testnet) for content
+  uploads.
 
 Install the CLI:
 
@@ -24,6 +31,8 @@ morse --version
 ## 1. Create a profile
 
 A profile pins the network. The first profile you add becomes the default.
+`--network` takes `mainnet`, `testnet`, or `localnet`; with no profile, flag, or
+`MORSE_NETWORK`, the CLI targets testnet.
 
 ```sh
 morse config add testnet --network testnet

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arcadiasystems/morse-cli",
-	"version": "0.4.2",
+	"version": "0.6.0",
 	"description": "Command-line interface for the Morse decentralized CMS on Sui.",
 	"license": "MIT",
 	"type": "module",
@@ -55,7 +55,7 @@
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
-		"@arcadiasystems/morse-sdk": "^0.4.2",
+		"@arcadiasystems/morse-sdk": "^0.5.0",
 		"@mysten/seal": "1.1.3",
 		"@mysten/sui": "2.16.2",
 		"@mysten/walrus": "1.1.6",