polkadot-cli 1.15.0 → 1.16.0

package/README.md

@@ -20,6 +20,8 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ Account management — BIP39 mnemonics, derivation paths, env-backed secrets, watch-only, dev accounts
 - ✅ Named address resolution across all commands
 - ✅ Runtime API calls — `dot polkadot.apis.Core.version`
+- ✅ Full-metadata dump — `dot metadata <chain>` emits one JSON blob with pallets, runtime APIs, and transaction extensions (or raw SCALE bytes via `--raw`)
+- ✅ Stale-metadata detection — when a tx or query fails because the runtime upgraded, the CLI tells you exactly which `dot chain update` to run
 - ✅ Chain topology — relay/parachain hierarchy with tree display and auto-detection
 - ✅ Batteries included — all system parachains and testnets already setup to be used
 - ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
@@ -577,6 +579,32 @@ The pallet listing view shows type information inline so you can understand item
 
 Documentation from the runtime metadata is shown on an indented line below each item. The detail view (`dot inspect Balances.transfer_allow_death`) shows the full argument signature and complete documentation text. Use call inspection to discover argument names, types, and docs before constructing `dot tx` commands.
 
+### Dump full metadata
+
+`dot metadata <chain>` fetches the chain's runtime metadata and prints **everything** as one JSON blob — pallets (with calls, events, errors, storage, constants), runtime APIs, and transaction extensions, headed by a runtime fingerprint (`specVersion`, `transactionVersion`, `codeHash`, etc.). Useful for feeding LLM agents or pipelines that want a single source of truth instead of walking `dot inspect` piecemeal.
+
+```bash
+# Decoded JSON — fetches fresh from the chain
+dot metadata polkadot
+
+# SCALE-encoded metadata bytes as a single 0x… hex line (for tools that re-parse)
+dot metadata polkadot --raw
+
+# Skip the network round-trip and use cached metadata
+dot metadata polkadot --cached
+
+# Override the RPC endpoint
+dot metadata polkadot --rpc wss://rpc.example.com
+
+# Slice with jq — list call names in a pallet
+dot metadata polkadot | jq '.pallets[] | select(.name=="Balances") | .calls[].name'
+
+# All transaction extension identifiers
+dot metadata polkadot | jq '.transactionExtensions[].identifier'
+```
+
+The decoded JSON is structured-only (no colorization), so it's safe to redirect to a file or pipe into other tools. The default fetches fresh from the RPC and atomically updates the local metadata cache and runtime-fingerprint sidecar — so subsequent commands benefit from the freshest possible metadata.
+
 ### Runtime APIs
 
 Browse and call Substrate runtime APIs. These are top-level APIs exposed by the runtime (e.g. `Core`, `AccountNonceApi`, `TransactionPaymentApi`), accessed as `dot <chain>.apis.ApiName.method`.
@@ -848,6 +876,22 @@ dot tx.Balances.transferKeepAlive 5FHneW46... 999999999999999999 --from alice --
 echo $?  # 1
 ```
 
+#### Stale metadata detection
+
+When a `tx`, `--dry-run`, or `query` fails with an error that smells like stale metadata — a runtime wasm trap, a SCALE codec/decode error, or a fee-estimation panic — the CLI compares your locally cached metadata's runtime fingerprint against the live chain. If it has changed, the CLI appends a one-line suggestion telling you exactly which command to run:
+
+```
+Error: The runtime rejected this transaction in the runtime's validate_transaction step.
+  Cause: a runtime invariant failed — typically the call's arguments are out of range, …
+
+⚠ Local metadata for "paseo-people-next" is out of date (spec 1018 → 1020).
+   Run: dot chain update paseo-people-next
+```
+
+The fingerprint includes the runtime code hash, so the check also catches local-node restarts where the wasm changed but `specVersion` was kept the same. No automatic refetch happens — the original error still propagates with a non-zero exit code, you just get an actionable suggestion.
+
+The check only fires on suspected-stale errors, so the happy path pays no extra RPC. Set `DOT_TRUST_CACHED_METADATA=1` to disable the check entirely (e.g. for CI loops where you've just refreshed manually).
+
 #### Argument parsing errors
 
 When a call argument is invalid, the CLI shows a contextual error message with the argument name, the expected type, and a hint:
@@ -1450,11 +1494,16 @@ Config and metadata caches live in `~/.polkadot/` by default:
 ├── update-check.json    # cached update check result
 └── chains/
     └── polkadot/
-        └── metadata.bin # cached SCALE-encoded metadata
+        ├── metadata.bin              # cached SCALE-encoded metadata
+        └── metadata.fingerprint.json # runtime fingerprint (specVersion, codeHash, …) for stale-metadata detection
 ```
 
 > **Warning:** `accounts.json` stores secrets (mnemonics and seeds) in **plain text**. Encrypted-at-rest storage is planned but not yet implemented. Keep appropriate file permissions (`chmod 600 ~/.polkadot/accounts.json`) and do not use this for high-value mainnet accounts.
 
+### `DOT_TRUST_CACHED_METADATA` — skip the staleness check
+
+Set `DOT_TRUST_CACHED_METADATA=1` to disable the post-failure stale-metadata check on `dot tx`, `dot tx --dry-run`, and `dot query`. When set, errors propagate exactly as the runtime / RPC reported them, with no extra `state_getRuntimeVersion` / `state_getStorageHash` round-trip. Useful in CI loops where you've just refreshed metadata manually and don't want the overhead.
+
 ### `DOT_HOME` — redirect the config directory
 
 Set the `DOT_HOME` environment variable to point at a different directory. When set, the CLI reads and writes **everything** (config, accounts, metadata, update cache) under that path — no `.polkadot` suffix is appended.

package/dist/cli.mjs

@@ -16,7 +16,31 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/utils/errors.ts
-var CliError, ConnectionError, MetadataError;
+function isLikelyStaleMetadataError(err) {
+  const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  if (!msg)
+    return false;
+  return STALE_METADATA_PATTERNS.some((re) => re.test(msg));
+}
+function formatRuntimeError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/wasm trap|wasm `?unreachable`? instruction|Execution aborted due to trap/i.test(msg)) {
+    const frames = Array.from(msg.matchAll(/\.wasm!([A-Za-z_]\w+)/g)).map((m) => m[1]);
+    const fn = [...frames].reverse().find((name) => !/^(?:__rustc|core::panicking|rust_begin_unwind|panic_fmt)/.test(name));
+    const where = fn?.includes("validate_transaction") ? "the runtime's validate_transaction step" : fn ? `runtime function ${fn}` : "the runtime";
+    return [
+      `The runtime rejected this transaction in ${where}.`,
+      "  Cause: a runtime invariant failed — typically the call's arguments are out of range, reference an unknown id, or violate a precondition.",
+      "  Tip:   re-check the arguments and the signing account's permissions; --dry-run will surface the same error before signing."
+    ].join(`
+`);
+  }
+  if (/Invalid Transaction/i.test(msg)) {
+    return `Transaction rejected as invalid by the runtime: ${msg}`;
+  }
+  return msg;
+}
+var CliError, ConnectionError, MetadataError, STALE_METADATA_PATTERNS;
 var init_errors = __esm(() => {
   CliError = class CliError extends Error {
     constructor(message) {
@@ -36,8 +60,28 @@ var init_errors = __esm(() => {
       this.name = "MetadataError";
     }
   };
+  STALE_METADATA_PATTERNS = [
+    /wasm trap/i,
+    /wasm `?unreachable`? instruction/i,
+    /Execution aborted due to trap/i,
+    /codec/i,
+    /decod(e|ing)/i,
+    /Lookup failed/i,
+    /metadata.*mismatch/i
+  ];
 });
 
+// src/utils/runtime-fingerprint.ts
+function fingerprintsMatch(a, b) {
+  return a.codeHash === b.codeHash && a.specVersion === b.specVersion && a.transactionVersion === b.transactionVersion;
+}
+function isRuntimeFingerprint(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const v = value;
+  return typeof v.specName === "string" && typeof v.specVersion === "number" && typeof v.transactionVersion === "number" && typeof v.implName === "string" && typeof v.implVersion === "number" && typeof v.authoringVersion === "number" && typeof v.codeHash === "string" && typeof v.fetchedAt === "string";
+}
+
 // src/config/types.ts
 function primaryRpc(rpc) {
   return Array.isArray(rpc) ? rpc[0] : rpc;
@@ -193,6 +237,9 @@ function getChainDir(chainName) {
 function getMetadataPath(chainName) {
   return join(getChainDir(chainName), "metadata.bin");
 }
+function getMetadataFingerprintPath(chainName) {
+  return join(getChainDir(chainName), "metadata.fingerprint.json");
+}
 function getConfigPath() {
   return join(getConfigDir(), "config.json");
 }
@@ -238,10 +285,25 @@ async function loadMetadata(chainName) {
   }
   return null;
 }
-async function saveMetadata(chainName, data) {
+async function saveMetadata(chainName, data, fingerprint) {
   const dir = getChainDir(chainName);
   await ensureDir(dir);
   await writeFile(getMetadataPath(chainName), data);
+  if (fingerprint) {
+    await writeFile(getMetadataFingerprintPath(chainName), `${JSON.stringify(fingerprint, null, 2)}
+`);
+  }
+}
+async function loadMetadataFingerprint(chainName) {
+  const path = getMetadataFingerprintPath(chainName);
+  if (!await fileExists(path))
+    return null;
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf-8"));
+    return isRuntimeFingerprint(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
 }
 async function removeChainData(chainName) {
   const dir = getChainDir(chainName);
@@ -809,28 +871,52 @@ function parseMetadata(raw) {
   const builder = getDynamicBuilder(lookup);
   return { unified, lookup, builder, version: version2 };
 }
+async function getRuntimeFingerprint(clientHandle, chainName) {
+  const { client } = clientHandle;
+  const [version2, codeHash] = await Promise.all([
+    withTimeout(client._request("state_getRuntimeVersion", []), chainName),
+    withTimeout(client._request("state_getStorageHash", ["0x3a636f6465"]), chainName)
+  ]);
+  return {
+    specName: version2.specName,
+    specVersion: version2.specVersion,
+    transactionVersion: version2.transactionVersion,
+    implName: version2.implName,
+    implVersion: version2.implVersion,
+    authoringVersion: version2.authoringVersion,
+    codeHash,
+    fetchedAt: new Date().toISOString()
+  };
+}
 async function fetchMetadataFromChain(clientHandle, chainName) {
   const { client } = clientHandle;
+  let bytes;
   try {
     const hex = await withTimeout(client._request("state_call", ["Metadata_metadata_at_version", v15Arg]), chainName);
     const raw = hexToBytes(hex);
     const decoded = optionalOpaqueBytes.dec(raw);
     if (decoded !== undefined) {
-      const bytes = new Uint8Array(decoded);
-      await saveMetadata(chainName, bytes);
-      return bytes;
+      bytes = new Uint8Array(decoded);
     }
   } catch {}
+  if (!bytes) {
+    try {
+      const hex = await withTimeout(client._request("state_getMetadata", []), chainName);
+      bytes = hexToBytes(hex);
+    } catch (err) {
+      if (err instanceof ConnectionError)
+        throw err;
+      throw new ConnectionError(`Failed to fetch metadata for "${chainName}": ${err instanceof Error ? err.message : err}. ` + "Check that the RPC endpoint is correct and reachable.");
+    }
+  }
+  let fingerprint;
   try {
-    const hex = await withTimeout(client._request("state_getMetadata", []), chainName);
-    const bytes = hexToBytes(hex);
-    await saveMetadata(chainName, bytes);
-    return bytes;
-  } catch (err) {
-    if (err instanceof ConnectionError)
-      throw err;
-    throw new ConnectionError(`Failed to fetch metadata for "${chainName}": ${err instanceof Error ? err.message : err}. ` + "Check that the RPC endpoint is correct and reachable.");
+    fingerprint = await getRuntimeFingerprint(clientHandle, chainName);
+  } catch {
+    fingerprint = undefined;
   }
+  await saveMetadata(chainName, bytes, fingerprint);
+  return bytes;
 }
 function withTimeout(promise, chainName) {
   return Promise.race([
@@ -838,6 +924,33 @@ function withTimeout(promise, chainName) {
     new Promise((_, reject) => setTimeout(() => reject(new ConnectionError(`Timed out fetching metadata for "${chainName}" after ${METADATA_TIMEOUT_MS / 1000}s. ` + "Check that the RPC endpoint is correct and reachable.")), METADATA_TIMEOUT_MS))
   ]);
 }
+async function withStalenessSuggestion(chainName, clientHandle, task) {
+  try {
+    return await task();
+  } catch (err) {
+    if (process.env.DOT_TRUST_CACHED_METADATA === "1")
+      throw err;
+    if (!isLikelyStaleMetadataError(err))
+      throw err;
+    let live;
+    try {
+      live = await getRuntimeFingerprint(clientHandle, chainName);
+    } catch {
+      throw err;
+    }
+    const cached = await loadMetadataFingerprint(chainName);
+    if (!cached)
+      throw err;
+    if (fingerprintsMatch(cached, live))
+      throw err;
+    const original = err instanceof Error ? formatRuntimeError(err) : String(err);
+    const versionNote = cached.specVersion !== live.specVersion ? `spec ${cached.specVersion} → ${live.specVersion}` : `runtime code hash changed (same spec ${live.specVersion}; likely a node restart with new wasm)`;
+    throw new CliError(`${original}
+
+` + `⚠ Local metadata for "${chainName}" is out of date (${versionNote}).
+` + `   Run: dot chain update ${chainName}`);
+  }
+}
 async function getOrFetchMetadata(chainName, clientHandle) {
   let raw = await loadMetadata(chainName);
   if (!raw) {
@@ -1251,7 +1364,10 @@ function normalizeValue(lookup, entry, value) {
         innerResolved = innerResolved.value;
       }
       if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
-        if (/^0x[0-9a-fA-F]*$/.test(value))
+        const isHex = /^0x[0-9a-fA-F]*$/.test(value);
+        if (resolved.type === "array" && isHex)
+          return value;
+        if (isHex)
           return Binary2.fromHex(value);
         return Binary2.fromText(value);
       }
@@ -2581,7 +2697,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.15.0";
+var version = "1.16.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -5078,6 +5194,61 @@ function registerInspectCommand(cli) {
   });
 }
 
+// src/commands/metadata.ts
+init_store();
+init_client();
+init_metadata();
+init_output();
+init_errors();
+function buildMetadataPayload(chainName, meta, fingerprint) {
+  return {
+    chain: chainName,
+    runtime: { ...fingerprint ?? {}, metadataVersion: meta.version },
+    pallets: listPallets(meta),
+    runtimeApis: listRuntimeApis(meta),
+    transactionExtensions: getSignedExtensions(meta)
+  };
+}
+async function handleMetadata(chain, opts) {
+  const config = await loadConfig();
+  const { name: chainName, chain: chainConfig } = resolveChain(config, chain);
+  let rawBytes;
+  if (opts.cached) {
+    rawBytes = await loadMetadata(chainName);
+    if (!rawBytes) {
+      throw new CliError(`No cached metadata for "${chainName}". Run \`dot chain update ${chainName}\` first, or omit --cached to fetch fresh.`);
+    }
+  } else {
+    const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
+    try {
+      await fetchMetadataFromChain(clientHandle, chainName);
+    } finally {
+      clientHandle.destroy();
+    }
+    rawBytes = await loadMetadata(chainName);
+    if (!rawBytes) {
+      throw new CliError(`Failed to load metadata for "${chainName}" after fetch.`);
+    }
+  }
+  if (opts.raw) {
+    await writeStdout(`0x${Buffer.from(rawBytes).toString("hex")}
+`);
+    return;
+  }
+  const meta = parseMetadata(rawBytes);
+  const fingerprint = await loadMetadataFingerprint(chainName);
+  await writeStdout(`${formatJson(buildMetadataPayload(chainName, meta, fingerprint))}
+`);
+}
+function writeStdout(text) {
+  return new Promise((resolve) => {
+    process.stdout.write(text, () => resolve());
+  });
+}
+function registerMetadataCommand(cli) {
+  cli.command("metadata <chain>", "Fetch chain metadata (decoded JSON; --raw for SCALE hex)").option("--raw", "Print SCALE-encoded metadata bytes as hex instead of decoded JSON").option("--cached", "Use cached metadata instead of fetching fresh from the chain").option("--rpc <url>", "Override RPC endpoint(s)").action((chain, opts) => handleMetadata(chain, opts));
+}
+
 // src/commands/parachain.ts
 init_accounts();
 init_output();
@@ -5273,13 +5444,13 @@ async function handleQuery(target, keys, opts) {
         console.log(`${DIM}Hint: use --dump to fetch all entries${RESET}`);
         return;
       }
-      const entries = await storageApi.getEntries(...parsedKeys);
+      const entries = await withStalenessSuggestion(chainName, clientHandle, () => storageApi.getEntries(...parsedKeys));
       printResult(entries.map((e) => ({
         keys: e.keyArgs,
         value: e.value
       })), format);
     } else {
-      const result = await storageApi.getValue(...parsedKeys);
+      const result = await withStalenessSuggestion(chainName, clientHandle, () => storageApi.getValue(...parsedKeys));
       printResult(result, format);
     }
   } finally {
@@ -5732,10 +5903,11 @@ async function handleTx(target, args, opts) {
     if (opts.dryRun) {
       const signerAddress = toSs58(signer.publicKey);
       let estimatedFees;
+      let estimationError;
       try {
-        estimatedFees = String(await tx.getEstimatedFees(signer?.publicKey, txOptions));
-      } catch {
-        estimatedFees = undefined;
+        estimatedFees = String(await withStalenessSuggestion(chainName, clientHandle, () => tx.getEstimatedFees(signer?.publicKey, txOptions)));
+      } catch (err) {
+        estimationError = err instanceof Error ? err.message : String(err);
       }
       if (isJsonOutput(opts)) {
         const result2 = {
@@ -5745,6 +5917,8 @@ async function handleTx(target, args, opts) {
           decoded: decodedStr,
           estimatedFees
         };
+        if (estimationError !== undefined)
+          result2.estimationError = estimationError;
         if (nonce !== undefined)
           result2.nonce = nonce;
         if (tip !== undefined)
@@ -5776,6 +5950,12 @@ async function handleTx(target, args, opts) {
         console.log(`  ${BOLD}Estimated fees:${RESET} ${estimatedFees}`);
       } else {
         console.log(`  ${BOLD}Estimated fees:${RESET} ${YELLOW}unable to estimate${RESET}`);
+        if (estimationError) {
+          const formatted = formatRuntimeError(estimationError).replace(/\n/g, `
+  `);
+          console.log(`  ${YELLOW}⚠${RESET} ${formatted}`);
+          console.log(`  ${DIM}Submitting this transaction is likely to fail.${RESET}`);
+        }
       }
       return;
     }
@@ -5795,7 +5975,7 @@ async function handleTx(target, args, opts) {
       }
       const observable = clientHandle.client.submitAndWatch(generalTx, at);
       if (isJsonOutput(opts)) {
-        const result3 = await watchTransactionJson(observable, waitLevel, { unsigned: true });
+        const result3 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransactionJson(observable, waitLevel, { unsigned: true }));
         const rpcUrl3 = primaryRpc(opts.rpc ?? chainConfig.rpc);
         if (result3.type === "broadcasted") {
           printJsonLine({ event: "broadcasted", txHash: result3.txHash });
@@ -5827,7 +6007,7 @@ async function handleTx(target, args, opts) {
         }
         return;
       }
-      const result2 = await watchTransaction(observable, waitLevel, { unsigned: true });
+      const result2 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransaction(observable, waitLevel, { unsigned: true }));
       console.log();
       console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
       console.log(`  ${BOLD}Type:${RESET}   unsigned (bare)`);
@@ -5876,7 +6056,7 @@ async function handleTx(target, args, opts) {
       return;
     }
     if (isJsonOutput(opts)) {
-      const result2 = await watchTransactionJson(tx.signSubmitAndWatch(signer, txOptions), waitLevel);
+      const result2 = await withStalenessSuggestion(chainName, clientHandle, () => watchTransactionJson(tx.signSubmitAndWatch(signer, txOptions), waitLevel));
       const rpcUrl2 = primaryRpc(opts.rpc ?? chainConfig.rpc);
       if (result2.type === "broadcasted") {
         printJsonLine({ event: "broadcasted", txHash: result2.txHash });
@@ -5907,7 +6087,7 @@ async function handleTx(target, args, opts) {
       }
       return;
     }
-    const result = await watchTransaction(tx.signSubmitAndWatch(signer, txOptions), waitLevel);
+    const result = await withStalenessSuggestion(chainName, clientHandle, () => watchTransaction(tx.signSubmitAndWatch(signer, txOptions), waitLevel));
     console.log();
     console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
     console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
@@ -6342,7 +6522,10 @@ function normalizeValue2(lookup, entry, value) {
         innerResolved = innerResolved.value;
       }
       if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
-        if (/^0x[0-9a-fA-F]*$/.test(value))
+        const isHex = /^0x[0-9a-fA-F]*$/.test(value);
+        if (resolved.type === "array" && isHex)
+          return value;
+        if (isHex)
           return Binary3.fromHex(value);
         return Binary3.fromText(value);
       }
@@ -7231,6 +7414,34 @@ class CliError2 extends Error {
     this.name = "CliError";
   }
 }
+var PAPI_CLEANUP_PATTERNS = [
+  /^Not connected$/,
+  /DisjointError/,
+  /ChainHead.*(aborted|stopped)/i
+];
+function isPapiCleanupError(err) {
+  if (!(err instanceof Error))
+    return false;
+  return PAPI_CLEANUP_PATTERNS.some((re) => re.test(err.message));
+}
+function formatRuntimeError2(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (/wasm trap|wasm `?unreachable`? instruction|Execution aborted due to trap/i.test(msg)) {
+    const frames = Array.from(msg.matchAll(/\.wasm!([A-Za-z_]\w+)/g)).map((m) => m[1]);
+    const fn = [...frames].reverse().find((name) => !/^(?:__rustc|core::panicking|rust_begin_unwind|panic_fmt)/.test(name));
+    const where = fn?.includes("validate_transaction") ? "the runtime's validate_transaction step" : fn ? `runtime function ${fn}` : "the runtime";
+    return [
+      `The runtime rejected this transaction in ${where}.`,
+      "  Cause: a runtime invariant failed — typically the call's arguments are out of range, reference an unknown id, or violate a precondition.",
+      "  Tip:   re-check the arguments and the signing account's permissions; --dry-run will surface the same error before signing."
+    ].join(`
+`);
+  }
+  if (/Invalid Transaction/i.test(msg)) {
+    return `Transaction rejected as invalid by the runtime: ${msg}`;
+  }
+  return msg;
+}
 
 // src/utils/parse-dot-path.ts
 var CATEGORY_ALIASES = {
@@ -7353,6 +7564,7 @@ if (process.argv[2] === "__complete") {
     console.log("  dot polkadot.const.Balances.ExistentialDeposit");
     console.log("  dot polkadot.events.Balances                        List events in Balances");
     console.log("  dot polkadot.apis.Core.version                      Call a runtime API");
+    console.log("  dot metadata polkadot                               Dump runtime metadata as JSON");
     console.log("  dot polkadot.extensions                             List transaction extensions");
     console.log("  dot polkadot.extensions.CheckMortality              Inspect one extension");
     console.log("  dot query.System.Number --chain polkadot            --chain flag form");
@@ -7363,6 +7575,7 @@ if (process.argv[2] === "__complete") {
     console.log();
     console.log("Commands:");
     console.log("  inspect [target]   Inspect chain metadata (alias: explore)");
+    console.log("  metadata <chain>   Dump runtime metadata as JSON (--raw for SCALE hex)");
     console.log("  chain              Manage chain configurations");
     console.log("  account            Manage accounts");
     console.log("  hash               Hash utilities");
@@ -7389,6 +7602,7 @@ if (process.argv[2] === "__complete") {
   cli.option("--json", "Output as JSON (shorthand for --output json)");
   registerChainCommands(cli);
   registerInspectCommand(cli);
+  registerMetadataCommand(cli);
   registerAccountCommands(cli);
   registerHashCommand(cli);
   registerSignCommand(cli);
@@ -7545,12 +7759,18 @@ if (process.argv[2] === "__complete") {
     if (err instanceof CliError2) {
       console.error(`Error: ${err.message}`);
     } else if (err instanceof Error) {
-      console.error(`Error: ${err.message}`);
+      console.error(`Error: ${formatRuntimeError2(err)}`);
     } else {
       console.error("An unexpected error occurred:", err);
     }
     return showUpdateAndExit(1);
   }
+  process.on("unhandledRejection", (reason) => {
+    if (isPapiCleanupError(reason))
+      return;
+    console.error(`Error: ${formatRuntimeError2(reason)}`);
+    process.exit(1);
+  });
   async function main() {
     try {
       cli.parse(process.argv, { run: false });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {
@@ -52,6 +52,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.5",
     "@changesets/cli": "^2.29.4",
+    "@polkadot-api/metadata-compatibility": "^0.6.1",
     "@types/bun": "^1.3.9",
     "husky": "^9.1.7"
   }