polkadot-cli 0.13.0 → 0.14.0

package/README.md

@@ -220,7 +220,7 @@ dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 # All map entries (default limit: 100)
 dot query System.Account --limit 10
 
-# Pipe to jq — stdout is clean JSON, no extra text
+# Pipe-safe — stdout is clean data, progress messages go to stderr
 dot query System.Account --limit 5 | jq '.[0].value.data.free'
 dot query System.Number --output json | jq '.+1'
 
@@ -249,7 +249,7 @@ dot const Balances.ExistentialDeposit
 dot const System.SS58Prefix --chain kusama
 dot const kusama.Balances.ExistentialDeposit
 
-# Pipe to jq — stdout is clean JSON, no extra text
+# Pipe-safe — stdout is clean JSON, progress messages go to stderr
 dot const Balances.ExistentialDeposit --output json | jq
 ```
 
@@ -258,10 +258,10 @@ dot const Balances.ExistentialDeposit --output json | jq
 Works offline from cached metadata after the first fetch.
 
 ```bash
-# List all pallets (shows storage, constants, and calls counts)
+# List all pallets (shows storage, constants, calls, events, and errors counts)
 dot inspect
 
-# List a pallet's storage items, constants, and calls
+# List a pallet's storage items, constants, calls, events, and errors
 dot inspect System
 
 # Detailed type info for a specific storage item or constant
@@ -270,12 +270,57 @@ dot inspect System.Account
 # Call detail — shows argument signature and docs
 dot inspect Balances.transfer_allow_death
 
+# Event detail — shows field signature and docs
+dot inspect Balances.Transfer
+
+# Error detail — shows docs
+dot inspect Balances.InsufficientBalance
+
 # Inspect a specific chain using chain prefix
 dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
-Use call inspection to discover argument names and types before constructing `dot tx` commands.
+The pallet listing view shows type information inline so you can understand item shapes at a glance:
+
+- **Storage**: key/value types with `[map]` tag for map items (e.g. `Account: AccountId32 → { nonce: u32, ... }    [map]`)
+- **Constants**: the constant's type (e.g. `ExistentialDeposit: u128`)
+- **Calls**: full argument signature (e.g. `transfer_allow_death(dest: enum(5 variants), value: Compact<u128>)`)
+- **Events**: field signature (e.g. `Transfer(from: AccountId32, to: AccountId32, amount: u128)`)
+- **Errors**: name and documentation (e.g. `InsufficientBalance`)
+
+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.
+
+### Focused commands
+
+Browse specific metadata categories directly without using `dot inspect`:
+
+```bash
+# List all pallets
+dot pallets
+
+# List pallet calls with argument signatures
+dot calls Balances
+dot calls Balances.transfer_allow_death   # call detail
+
+# List pallet events with field signatures
+dot events Balances
+dot events Balances.Transfer              # event detail
+
+# List pallet errors
+dot errors Balances
+dot errors Balances.InsufficientBalance   # error detail
+
+# List pallet storage items with types
+dot storage System
+dot storage System.Account               # storage detail
+
+# List pallet constants (dual-purpose — also works as value lookup)
+dot const Balances                        # list constants
+dot const Balances.ExistentialDeposit     # look up value
+```
+
+Each command supports `--chain <name>`, `--rpc <url>`, and chain prefix syntax. Singular and plural forms are interchangeable (e.g. `dot call` = `dot calls`, `dot event` = `dot events`).
 
 ### Submit extrinsics
 
@@ -431,6 +476,17 @@ dot hash --help         # same as `dot hash` — shows algorithms and examples
 | `--output json` | Raw JSON output (default: pretty) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
 
+### Pipe-safe output
+
+All commands follow Unix conventions: **data goes to stdout, progress goes to stderr**. This means you can safely pipe `--output json` into `jq` or other tools without progress messages ("Fetching metadata...", spinner output, "Connecting...") corrupting the data stream:
+
+```bash
+dot const System.SS58Prefix --output json | jq '.+1'
+dot query System.Number --output json | jq
+```
+
+In an interactive terminal, both streams render together so you see progress and results normally.
+
 ## How it compares
 
 | | polkadot-cli | @polkadot/api-cli | subxt-cli | Pop CLI |

package/dist/cli.mjs

@@ -5,7 +5,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "0.13.0";
+var version = "0.14.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -429,7 +429,7 @@ class Spinner {
   start(msg) {
     this.stop();
     if (!isTTY) {
-      console.log(msg);
+      console.error(msg);
       return;
     }
     process.stdout.write(`${SPINNER_FRAMES[0]} ${msg}`);
@@ -449,9 +449,16 @@ class Spinner {
   }
   succeed(msg) {
     this.stop();
-    console.log(`${GREEN}${CHECK_MARK}${RESET} ${msg}`);
+    console.error(`${GREEN}${CHECK_MARK}${RESET} ${msg}`);
   }
 }
+function firstSentence(docs) {
+  const text = docs.join(" ").trim();
+  if (!text)
+    return "";
+  const match = text.match(/^.*?(?<![ei]\.g|[ei]\.[eg])(?<!\betc)[.!?](?:\s|$)/);
+  return match ? match[0].trim() : text;
+}
 
 // src/commands/account.ts
 var ACCOUNT_HELP = `
@@ -977,26 +984,28 @@ function listPallets(meta) {
       docs: c.docs ?? [],
       typeId: c.type
     })),
-    calls: extractCalls(meta, p.calls)
+    calls: extractEnumVariants(meta, p.calls),
+    events: extractEnumVariants(meta, p.events),
+    errors: extractEnumVariants(meta, p.errors).map(({ name, docs }) => ({ name, docs }))
   }));
 }
-function extractCalls(meta, callsRef) {
-  if (!callsRef)
+function extractEnumVariants(meta, ref) {
+  if (!ref)
     return [];
   try {
-    const entry = meta.lookup(callsRef.type);
+    const entry = meta.lookup(ref.type);
     if (entry.type !== "enum")
       return [];
     return Object.entries(entry.value).map(([name, variant]) => ({
       name,
-      docs: variant.docs ?? [],
-      typeId: resolveCallTypeId(variant)
+      docs: entry.innerDocs?.[name] ?? [],
+      typeId: resolveVariantTypeId(variant)
     }));
   } catch {
     return [];
   }
 }
-function resolveCallTypeId(variant) {
+function resolveVariantTypeId(variant) {
   if (variant.type === "lookupEntry")
     return variant.value?.id ?? null;
   if (variant.type === "struct")
@@ -1095,6 +1104,42 @@ function describeCallArgs(meta, palletName, callName) {
     return "";
   }
 }
+function describeEventFields(meta, palletName, eventName) {
+  try {
+    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
+    if (!palletMeta?.events)
+      return "";
+    const eventsEntry = meta.lookup(palletMeta.events.type);
+    if (eventsEntry.type !== "enum")
+      return "";
+    const variant = eventsEntry.value[eventName];
+    if (!variant)
+      return "";
+    if (variant.type === "void")
+      return "()";
+    if (variant.type === "struct") {
+      const fields = Object.entries(variant.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
+      return `(${fields})`;
+    }
+    if (variant.type === "lookupEntry") {
+      const inner = variant.value;
+      if (inner.type === "void")
+        return "()";
+      if (inner.type === "struct") {
+        const fields = Object.entries(inner.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
+        return `(${fields})`;
+      }
+      return `(${formatLookupEntry(inner)})`;
+    }
+    if (variant.type === "tuple") {
+      const types = variant.value.map(formatLookupEntry).join(", ");
+      return `(${types})`;
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
 function hexToBytes(hex) {
   const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
   const bytes = new Uint8Array(clean.length / 2);
@@ -1170,10 +1215,10 @@ async function chainAdd(name, opts) {
     rpc: opts.rpc ?? "",
     ...opts.lightClient ? { lightClient: true } : {}
   };
-  console.log(`Connecting to ${name}...`);
+  console.error(`Connecting to ${name}...`);
   const clientHandle = await createChainClient(name, chainConfig, opts.rpc);
   try {
-    console.log("Fetching metadata...");
+    console.error("Fetching metadata...");
     await fetchMetadataFromChain(clientHandle, name);
     const config = await loadConfig();
     config.chains[name] = chainConfig;
@@ -1226,10 +1271,10 @@ async function chainList() {
 async function chainUpdate(name, opts) {
   const config = await loadConfig();
   const { name: chainName, chain: chainConfig } = resolveChain(config, name);
-  console.log(`Connecting to ${chainName}...`);
+  console.error(`Connecting to ${chainName}...`);
   const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
   try {
-    console.log("Fetching metadata...");
+    console.error("Fetching metadata...");
     await fetchMetadataFromChain(clientHandle, chainName);
     console.log(`Metadata for "${chainName}" updated.`);
   } finally {
@@ -1339,23 +1384,58 @@ function resolveTargetChain(target, chainFlag) {
 
 // src/commands/const.ts
 function registerConstCommand(cli) {
-  cli.command("const [target]", "Look up a pallet constant (e.g. Balances.ExistentialDeposit)").action(async (target, opts) => {
+  cli.command("const [target]", "Look up or list pallet constants (e.g. Balances.ExistentialDeposit)").alias("consts").alias("constants").action(async (target, opts) => {
     if (!target) {
-      console.log("Usage: dot const <[Chain.]Pallet.Constant> [--chain <name>] [--output json]");
+      console.log("Usage: dot const <[Chain.]Pallet[.Constant]> [--chain <name>] [--output json]");
       console.log("");
       console.log("Examples:");
-      console.log("  $ dot const Balances.ExistentialDeposit");
+      console.log("  $ dot const Balances                              # list constants");
+      console.log("  $ dot const Balances.ExistentialDeposit           # look up value");
       console.log("  $ dot const System.SS58Prefix --chain kusama");
       console.log("  $ dot const kusama.Balances.ExistentialDeposit    # chain prefix");
       return;
     }
     const config = await loadConfig();
     const knownChains = Object.keys(config.chains);
-    const parsed = parseTarget(target, { knownChains });
+    const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
     const effectiveChain = resolveTargetChain(parsed, opts.chain);
     const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
     const pallet = parsed.pallet;
     const item = parsed.item;
+    if (!item) {
+      let meta;
+      try {
+        meta = await getOrFetchMetadata(chainName);
+      } catch {
+        console.error(`Fetching metadata from ${chainName}...`);
+        const clientHandle2 = await createChainClient(chainName, chainConfig, opts.rpc);
+        try {
+          meta = await getOrFetchMetadata(chainName, clientHandle2);
+        } finally {
+          clientHandle2.destroy();
+        }
+      }
+      const palletNames = getPalletNames(meta);
+      const palletInfo = findPallet(meta, pallet);
+      if (!palletInfo) {
+        throw new Error(suggestMessage("pallet", pallet, palletNames));
+      }
+      if (palletInfo.constants.length === 0) {
+        console.log(`No constants in ${palletInfo.name}.`);
+        return;
+      }
+      printHeading(`${palletInfo.name} Constants`);
+      for (const c of palletInfo.constants) {
+        const typeStr = describeType(meta.lookup, c.typeId);
+        console.log(`  ${CYAN}${c.name}${RESET}${DIM}: ${typeStr}${RESET}`);
+        const summary = firstSentence(c.docs);
+        if (summary) {
+          console.log(`      ${DIM}${summary}${RESET}`);
+        }
+      }
+      console.log();
+      return;
+    }
     const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
     try {
       const meta = await getOrFetchMetadata(chainName, clientHandle);
@@ -1380,6 +1460,279 @@ function registerConstCommand(cli) {
   });
 }
 
+// src/commands/focused-inspect.ts
+async function loadMeta(chainName, chainConfig, rpcOverride) {
+  try {
+    return await getOrFetchMetadata(chainName);
+  } catch {
+    console.error(`Fetching metadata from ${chainName}...`);
+    const clientHandle = await createChainClient(chainName, chainConfig, rpcOverride);
+    try {
+      return await getOrFetchMetadata(chainName, clientHandle);
+    } finally {
+      clientHandle.destroy();
+    }
+  }
+}
+function resolvePallet(meta, palletName) {
+  const palletNames = getPalletNames(meta);
+  const pallet = findPallet(meta, palletName);
+  if (!pallet) {
+    throw new Error(suggestMessage("pallet", palletName, palletNames));
+  }
+  return pallet;
+}
+function registerFocusedInspectCommands(cli) {
+  cli.command("call [target]", "List or inspect pallet calls").alias("calls").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    if (!target) {
+      console.log("Usage: dot calls <[Chain.]Pallet[.Call]> [--chain <name>]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot calls Balances");
+      console.log("  $ dot calls Balances.transfer_allow_death");
+      return;
+    }
+    const config = await loadConfig();
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const meta = await loadMeta(chainName, chainConfig, opts.rpc);
+    const pallet = resolvePallet(meta, parsed.pallet);
+    if (!parsed.item) {
+      if (pallet.calls.length === 0) {
+        console.log(`No calls in ${pallet.name}.`);
+        return;
+      }
+      printHeading(`${pallet.name} Calls`);
+      for (const c of pallet.calls) {
+        const args2 = describeCallArgs(meta, pallet.name, c.name);
+        console.log(`  ${CYAN}${c.name}${RESET}${DIM}${args2}${RESET}`);
+        const summary = firstSentence(c.docs);
+        if (summary) {
+          console.log(`      ${DIM}${summary}${RESET}`);
+        }
+      }
+      console.log();
+      return;
+    }
+    const callItem = pallet.calls.find((c) => c.name.toLowerCase() === parsed.item.toLowerCase());
+    if (!callItem) {
+      const names = pallet.calls.map((c) => c.name);
+      throw new Error(suggestMessage(`call in ${pallet.name}`, parsed.item, names));
+    }
+    printHeading(`${pallet.name}.${callItem.name} (Call)`);
+    const args = describeCallArgs(meta, pallet.name, callItem.name);
+    console.log(`  ${BOLD}Args:${RESET} ${args}`);
+    if (callItem.docs.length) {
+      console.log();
+      printDocs(callItem.docs);
+    }
+    console.log();
+  });
+  cli.command("event [target]", "List or inspect pallet events").alias("events").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    if (!target) {
+      console.log("Usage: dot events <[Chain.]Pallet[.Event]> [--chain <name>]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot events Balances");
+      console.log("  $ dot events Balances.Transfer");
+      return;
+    }
+    const config = await loadConfig();
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const meta = await loadMeta(chainName, chainConfig, opts.rpc);
+    const pallet = resolvePallet(meta, parsed.pallet);
+    if (!parsed.item) {
+      if (pallet.events.length === 0) {
+        console.log(`No events in ${pallet.name}.`);
+        return;
+      }
+      printHeading(`${pallet.name} Events`);
+      for (const e of pallet.events) {
+        const fields2 = describeEventFields(meta, pallet.name, e.name);
+        console.log(`  ${CYAN}${e.name}${RESET}${DIM}${fields2}${RESET}`);
+        const summary = firstSentence(e.docs);
+        if (summary) {
+          console.log(`      ${DIM}${summary}${RESET}`);
+        }
+      }
+      console.log();
+      return;
+    }
+    const eventItem = pallet.events.find((e) => e.name.toLowerCase() === parsed.item.toLowerCase());
+    if (!eventItem) {
+      const names = pallet.events.map((e) => e.name);
+      throw new Error(suggestMessage(`event in ${pallet.name}`, parsed.item, names));
+    }
+    printHeading(`${pallet.name}.${eventItem.name} (Event)`);
+    const fields = describeEventFields(meta, pallet.name, eventItem.name);
+    console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
+    if (eventItem.docs.length) {
+      console.log();
+      printDocs(eventItem.docs);
+    }
+    console.log();
+  });
+  cli.command("error [target]", "List or inspect pallet errors").alias("errors").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    if (!target) {
+      console.log("Usage: dot errors <[Chain.]Pallet[.Error]> [--chain <name>]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot errors Balances");
+      console.log("  $ dot errors Balances.InsufficientBalance");
+      return;
+    }
+    const config = await loadConfig();
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const meta = await loadMeta(chainName, chainConfig, opts.rpc);
+    const pallet = resolvePallet(meta, parsed.pallet);
+    if (!parsed.item) {
+      if (pallet.errors.length === 0) {
+        console.log(`No errors in ${pallet.name}.`);
+        return;
+      }
+      printHeading(`${pallet.name} Errors`);
+      for (const e of pallet.errors) {
+        console.log(`  ${CYAN}${e.name}${RESET}`);
+        const summary = firstSentence(e.docs);
+        if (summary) {
+          console.log(`      ${DIM}${summary}${RESET}`);
+        }
+      }
+      console.log();
+      return;
+    }
+    const errorItem = pallet.errors.find((e) => e.name.toLowerCase() === parsed.item.toLowerCase());
+    if (!errorItem) {
+      const names = pallet.errors.map((e) => e.name);
+      throw new Error(suggestMessage(`error in ${pallet.name}`, parsed.item, names));
+    }
+    printHeading(`${pallet.name}.${errorItem.name} (Error)`);
+    if (errorItem.docs.length) {
+      printDocs(errorItem.docs);
+    }
+    console.log();
+  });
+  cli.command("storage [target]", "List or inspect pallet storage items").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    if (!target) {
+      console.log("Usage: dot storage <[Chain.]Pallet[.Item]> [--chain <name>]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot storage System");
+      console.log("  $ dot storage System.Account");
+      return;
+    }
+    const config = await loadConfig();
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const meta = await loadMeta(chainName, chainConfig, opts.rpc);
+    const pallet = resolvePallet(meta, parsed.pallet);
+    if (!parsed.item) {
+      if (pallet.storage.length === 0) {
+        console.log(`No storage items in ${pallet.name}.`);
+        return;
+      }
+      printHeading(`${pallet.name} Storage`);
+      for (const s of pallet.storage) {
+        const valueType = describeType(meta.lookup, s.valueTypeId);
+        let typeSuffix;
+        if (s.keyTypeId != null) {
+          const keyType = describeType(meta.lookup, s.keyTypeId);
+          typeSuffix = `: ${keyType} → ${valueType}    [map]`;
+        } else {
+          typeSuffix = `: ${valueType}`;
+        }
+        console.log(`  ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+        const summary = firstSentence(s.docs);
+        if (summary) {
+          console.log(`      ${DIM}${summary}${RESET}`);
+        }
+      }
+      console.log();
+      return;
+    }
+    const storageItem = pallet.storage.find((s) => s.name.toLowerCase() === parsed.item.toLowerCase());
+    if (!storageItem) {
+      const names = pallet.storage.map((s) => s.name);
+      throw new Error(suggestMessage(`storage item in ${pallet.name}`, parsed.item, names));
+    }
+    printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
+    console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
+    console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+    if (storageItem.keyTypeId != null) {
+      console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+    }
+    if (storageItem.docs.length) {
+      console.log();
+      printDocs(storageItem.docs);
+    }
+    console.log();
+  });
+  cli.command("pallet [target]", "List all pallets or inspect a specific pallet").alias("pallets").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    const config = await loadConfig();
+    const knownChains = Object.keys(config.chains);
+    let effectiveChain = opts.chain;
+    let palletName;
+    if (target) {
+      const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+      effectiveChain = resolveTargetChain(parsed, opts.chain);
+      palletName = parsed.pallet;
+    }
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const meta = await loadMeta(chainName, chainConfig, opts.rpc);
+    if (!palletName) {
+      const pallets = listPallets(meta);
+      printHeading(`Pallets on ${chainName} (${pallets.length})`);
+      for (const p of pallets) {
+        const counts2 = [];
+        if (p.storage.length)
+          counts2.push(`${p.storage.length} storage`);
+        if (p.constants.length)
+          counts2.push(`${p.constants.length} constants`);
+        if (p.calls.length)
+          counts2.push(`${p.calls.length} calls`);
+        if (p.events.length)
+          counts2.push(`${p.events.length} events`);
+        if (p.errors.length)
+          counts2.push(`${p.errors.length} errors`);
+        printItem(p.name, counts2.join(", "));
+      }
+      console.log();
+      return;
+    }
+    const pallet = resolvePallet(meta, palletName);
+    printHeading(`${pallet.name} Pallet`);
+    if (pallet.docs.length) {
+      printDocs(pallet.docs);
+      console.log();
+    }
+    const counts = [];
+    if (pallet.storage.length)
+      counts.push(`${pallet.storage.length} storage`);
+    if (pallet.constants.length)
+      counts.push(`${pallet.constants.length} constants`);
+    if (pallet.calls.length)
+      counts.push(`${pallet.calls.length} calls`);
+    if (pallet.events.length)
+      counts.push(`${pallet.events.length} events`);
+    if (pallet.errors.length)
+      counts.push(`${pallet.errors.length} errors`);
+    if (counts.length) {
+      console.log(`  ${counts.join(", ")}`);
+    }
+    console.log();
+  });
+}
+
 // src/core/hash.ts
 import { blake2b } from "@noble/hashes/blake2.js";
 import { sha256 } from "@noble/hashes/sha2.js";
@@ -1513,7 +1866,7 @@ function registerHashCommand(cli) {
 
 // src/commands/inspect.ts
 function registerInspectCommand(cli) {
-  cli.command("inspect [target]", "Inspect chain metadata (pallets, storage, constants)").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+  cli.command("inspect [target]", "Inspect chain metadata (pallets, storage, constants, calls, events, errors)").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
     const config = await loadConfig();
     const knownChains = Object.keys(config.chains);
     let effectiveChain = opts.chain;
@@ -1530,7 +1883,7 @@ function registerInspectCommand(cli) {
     try {
       meta = await getOrFetchMetadata(chainName);
     } catch {
-      console.log(`Fetching metadata from ${chainName}...`);
+      console.error(`Fetching metadata from ${chainName}...`);
       const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
       try {
         meta = await getOrFetchMetadata(chainName, clientHandle);
@@ -1549,6 +1902,10 @@ function registerInspectCommand(cli) {
           counts.push(`${p.constants.length} constants`);
         if (p.calls.length)
           counts.push(`${p.calls.length} calls`);
+        if (p.events.length)
+          counts.push(`${p.events.length} events`);
+        if (p.errors.length)
+          counts.push(`${p.errors.length} errors`);
         printItem(p.name, counts.join(", "));
       }
       console.log();
@@ -1568,24 +1925,66 @@ function registerInspectCommand(cli) {
       if (pallet2.storage.length) {
         console.log(`  ${BOLD}Storage Items:${RESET}`);
         for (const s of pallet2.storage) {
-          const doc = s.docs[0] ? ` — ${s.docs[0].slice(0, 80)}` : "";
-          console.log(`    ${CYAN}${s.name}${RESET}${DIM}${doc}${RESET}`);
+          const valueType = describeType(meta.lookup, s.valueTypeId);
+          let typeSuffix;
+          if (s.keyTypeId != null) {
+            const keyType = describeType(meta.lookup, s.keyTypeId);
+            typeSuffix = `: ${keyType} → ${valueType}    [map]`;
+          } else {
+            typeSuffix = `: ${valueType}`;
+          }
+          console.log(`    ${CYAN}${s.name}${RESET}${DIM}${typeSuffix}${RESET}`);
+          const summary = firstSentence(s.docs);
+          if (summary) {
+            console.log(`        ${DIM}${summary}${RESET}`);
+          }
         }
         console.log();
       }
       if (pallet2.constants.length) {
         console.log(`  ${BOLD}Constants:${RESET}`);
         for (const c of pallet2.constants) {
-          const doc = c.docs[0] ? ` — ${c.docs[0].slice(0, 80)}` : "";
-          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${doc}${RESET}`);
+          const typeStr = describeType(meta.lookup, c.typeId);
+          console.log(`    ${CYAN}${c.name}${RESET}${DIM}: ${typeStr}${RESET}`);
+          const summary = firstSentence(c.docs);
+          if (summary) {
+            console.log(`        ${DIM}${summary}${RESET}`);
+          }
         }
         console.log();
       }
       if (pallet2.calls.length) {
         console.log(`  ${BOLD}Calls:${RESET}`);
         for (const c of pallet2.calls) {
-          const doc = c.docs[0] ? ` — ${c.docs[0].slice(0, 80)}` : "";
-          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${doc}${RESET}`);
+          const args = describeCallArgs(meta, pallet2.name, c.name);
+          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${args}${RESET}`);
+          const summary = firstSentence(c.docs);
+          if (summary) {
+            console.log(`        ${DIM}${summary}${RESET}`);
+          }
+        }
+        console.log();
+      }
+      if (pallet2.events.length) {
+        console.log(`  ${BOLD}Events:${RESET}`);
+        for (const e of pallet2.events) {
+          const fields = describeEventFields(meta, pallet2.name, e.name);
+          console.log(`    ${CYAN}${e.name}${RESET}${DIM}${fields}${RESET}`);
+          const summary = firstSentence(e.docs);
+          if (summary) {
+            console.log(`        ${DIM}${summary}${RESET}`);
+          }
+        }
+        console.log();
+      }
+      if (pallet2.errors.length) {
+        console.log(`  ${BOLD}Errors:${RESET}`);
+        for (const e of pallet2.errors) {
+          console.log(`    ${CYAN}${e.name}${RESET}`);
+          const summary = firstSentence(e.docs);
+          if (summary) {
+            console.log(`        ${DIM}${summary}${RESET}`);
+          }
         }
         console.log();
       }
@@ -1634,10 +2033,33 @@ function registerInspectCommand(cli) {
       console.log();
       return;
     }
+    const eventItem = pallet.events.find((e) => e.name.toLowerCase() === itemName.toLowerCase());
+    if (eventItem) {
+      printHeading(`${pallet.name}.${eventItem.name} (Event)`);
+      const fields = describeEventFields(meta, pallet.name, eventItem.name);
+      console.log(`  ${BOLD}Fields:${RESET} ${fields}`);
+      if (eventItem.docs.length) {
+        console.log();
+        printDocs(eventItem.docs);
+      }
+      console.log();
+      return;
+    }
+    const errorItem = pallet.errors.find((e) => e.name.toLowerCase() === itemName.toLowerCase());
+    if (errorItem) {
+      printHeading(`${pallet.name}.${errorItem.name} (Error)`);
+      if (errorItem.docs.length) {
+        printDocs(errorItem.docs);
+      }
+      console.log();
+      return;
+    }
     const allItems = [
       ...pallet.storage.map((s) => s.name),
       ...pallet.constants.map((c) => c.name),
-      ...pallet.calls.map((c) => c.name)
+      ...pallet.calls.map((c) => c.name),
+      ...pallet.events.map((e) => e.name),
+      ...pallet.errors.map((e) => e.name)
     ];
     throw new Error(suggestMessage(`item in ${pallet.name}`, itemName, allItems));
   });
@@ -2970,6 +3392,7 @@ registerChainCommands(cli);
 registerInspectCommand(cli);
 registerQueryCommand(cli);
 registerConstCommand(cli);
+registerFocusedInspectCommands(cli);
 registerAccountCommands(cli);
 registerTxCommand(cli);
 registerHashCommand(cli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {