polkadot-cli 0.6.2 → 0.8.0

package/README.md

@@ -1,3 +1,5 @@
+[![codecov](https://codecov.io/gh/peetzweg/polkadot-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/peetzweg/polkadot-cli)
+
 # polkadot-cli
 
 A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from your terminal.
@@ -22,7 +24,8 @@ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 dot chain add westend --light-client
 
 # List configured chains
-dot chain list
+dot chains              # shorthand
+dot chain list          # equivalent
 
 # Re-fetch metadata after a runtime upgrade
 dot chain update          # updates default chain
@@ -43,7 +46,8 @@ Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for t
 
 ```bash
 # List all accounts (dev + stored)
-dot account list
+dot accounts            # shorthand
+dot account list        # equivalent
 
 # Create a new account (generates a mnemonic)
 dot account create my-validator
@@ -64,6 +68,20 @@ dot account remove my-validator
 
 **Known limitation:** Hex seed import (`--secret 0x...`) does not work from the command line. The CLI argument parser (`cac`) interprets `0x`-prefixed values as JavaScript numbers, which loses precision for 32-byte seeds. Use a BIP39 mnemonic instead. If you need to import a raw seed programmatically, write it directly to `~/.polkadot/accounts.json`.
 
+### Chain prefix
+
+Instead of the `--chain` flag, you can prefix any target with the chain name using dot notation:
+
+```bash
+dot query kusama.System.Account 5GrwvaEF...
+dot const kusama.Balances.ExistentialDeposit
+dot tx kusama.Balances.transferKeepAlive 5FHneW46... 1000000000000 --from alice
+dot inspect kusama.System
+dot inspect kusama.System.Account
+```
+
+The `--chain` flag and default chain still work as before. If both a chain prefix and `--chain` flag are provided, the CLI errors.
+
 ### Query storage
 
 ```bash
@@ -78,6 +96,9 @@ dot query System.Account --limit 10
 
 # Pipe to jq (colors disabled automatically)
 dot query System.Account --limit 5 | jq '.[0].value.data.free'
+
+# Query a specific chain using chain prefix
+dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
 ### Look up constants
@@ -85,6 +106,7 @@ dot query System.Account --limit 5 | jq '.[0].value.data.free'
 ```bash
 dot const Balances.ExistentialDeposit
 dot const System.SS58Prefix --chain kusama
+dot const kusama.Balances.ExistentialDeposit
 ```
 
 ### Inspect metadata
@@ -100,6 +122,10 @@ dot inspect System
 
 # Detailed type info for a specific item
 dot inspect System.Account
+
+# Inspect a specific chain using chain prefix
+dot inspect kusama.System
+dot inspect kusama.System.Account
 ```
 
 ### Submit extrinsics
@@ -220,6 +246,27 @@ polkadot-cli aims to be the single tool for day-to-day chain interaction: storag
 
 Outside Polkadot, the closest comparable in terms of interactive UX is [near-cli-rs](https://github.com/near/near-cli-rs) (NEAR).
 
+## Update notifications
+
+After each command, the CLI checks whether a newer version is available on npm and displays a notification:
+
+```
+╭───────────────────────────────────────────────╮
+│                                               │
+│   Update available! 0.6.2 → 0.7.0            │
+│   Run npm i -g polkadot-cli to update         │
+│                                               │
+╰───────────────────────────────────────────────╯
+```
+
+The version check runs in the background on startup and caches the result for 24 hours in `~/.polkadot/update-check.json`. It never blocks the CLI.
+
+The notification is automatically suppressed when:
+
+- `DOT_NO_UPDATE_CHECK=1` is set
+- `CI` environment variable is set (any value)
+- stdout is not a TTY (e.g. piped output)
+
 ## Configuration
 
 Config and metadata caches live in `~/.polkadot/`:
@@ -228,6 +275,7 @@ Config and metadata caches live in `~/.polkadot/`:
 ~/.polkadot/
 ├── config.json          # chains and default chain
 ├── accounts.json        # stored accounts (⚠️ secrets are NOT encrypted — see below)
+├── update-check.json    # cached update check result
 └── chains/
     └── polkadot/
         └── metadata.bin # cached SCALE-encoded metadata

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.6.2";
+var version = "0.8.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -317,10 +317,9 @@ ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       Hex seed import (0x...) is not supported via CLI.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [name]", "Manage local accounts (create, import, list, remove)").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").action(async (action, name, opts) => {
+  cli.command("account [action] [name]", "Manage local accounts (create, import, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").action(async (action, name, opts) => {
     if (!action) {
-      console.log(ACCOUNT_HELP);
-      return;
+      return accountList();
     }
     switch (action) {
       case "create":
@@ -697,10 +696,9 @@ ${BOLD}Examples:${RESET}
   $ dot chain remove kusama
 `.trimStart();
 function registerChainCommands(cli) {
-  cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").action(async (action, name, opts) => {
+  cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").alias("chains").action(async (action, name, opts) => {
     if (!action) {
-      console.log(CHAIN_HELP);
-      return;
+      return chainList();
     }
     switch (action) {
       case "add":
@@ -850,28 +848,73 @@ function suggestMessage(kind, input, candidates) {
 }
 
 // src/utils/parse-target.ts
-function parseTarget(input) {
+function parseTarget(input, options) {
   const parts = input.split(".");
-  if (parts.length !== 2 || !parts[0] || !parts[1]) {
-    throw new Error(`Invalid target "${input}". Expected format: Pallet.Item (e.g. System.Account)`);
+  if (options?.allowPalletOnly) {
+    switch (parts.length) {
+      case 1:
+        if (!parts[0]) {
+          throw new Error(`Invalid target "${input}". Expected format: Pallet or Pallet.Item (e.g. System or System.Account)`);
+        }
+        return { pallet: parts[0] };
+      case 2:
+        if (!parts[0] || !parts[1]) {
+          throw new Error(`Invalid target "${input}". Expected format: Pallet.Item or Chain.Pallet (e.g. System.Account or kusama.System)`);
+        }
+        if (options.knownChains?.some((c) => c.toLowerCase() === parts[0].toLowerCase())) {
+          return { chain: parts[0], pallet: parts[1] };
+        }
+        return { pallet: parts[0], item: parts[1] };
+      case 3:
+        if (!parts[0] || !parts[1] || !parts[2]) {
+          throw new Error(`Invalid target "${input}". Expected format: Chain.Pallet.Item (e.g. kusama.System.Account)`);
+        }
+        return { chain: parts[0], pallet: parts[1], item: parts[2] };
+      default:
+        throw new Error(`Invalid target "${input}". Expected format: Pallet, Pallet.Item, or Chain.Pallet.Item`);
+    }
+  }
+  switch (parts.length) {
+    case 2:
+      if (!parts[0] || !parts[1]) {
+        throw new Error(`Invalid target "${input}". Expected format: Pallet.Item (e.g. System.Account)`);
+      }
+      return { pallet: parts[0], item: parts[1] };
+    case 3:
+      if (!parts[0] || !parts[1] || !parts[2]) {
+        throw new Error(`Invalid target "${input}". Expected format: Chain.Pallet.Item (e.g. kusama.System.Account)`);
+      }
+      return { chain: parts[0], pallet: parts[1], item: parts[2] };
+    default:
+      throw new Error(`Invalid target "${input}". Expected format: Pallet.Item (e.g. System.Account)`);
+  }
+}
+function resolveTargetChain(target, chainFlag) {
+  if (target.chain && chainFlag) {
+    throw new Error(`Chain specified both as prefix ("${target.chain}") and as --chain flag ("${chainFlag}"). Use one or the other.`);
   }
-  return { pallet: parts[0], item: parts[1] };
+  return target.chain ?? 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) => {
     if (!target) {
-      console.log("Usage: dot const <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 System.SS58Prefix --chain kusama");
+      console.log("  $ dot const kusama.Balances.ExistentialDeposit    # chain prefix");
       return;
     }
     const config = await loadConfig();
-    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
-    const { pallet, item } = parseTarget(target);
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const pallet = parsed.pallet;
+    const item = parsed.item;
     const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
     try {
       const meta = await getOrFetchMetadata(chainName, clientHandle);
@@ -888,7 +931,14 @@ function registerConstCommand(cli) {
       const unsafeApi = clientHandle.client.getUnsafeApi();
       const runtimeToken = await unsafeApi.runtimeToken;
       const result = unsafeApi.constants[palletInfo.name][constantItem.name](runtimeToken);
-      printResult(result, opts.output ?? "pretty");
+      const format = opts.output ?? "pretty";
+      if (format === "json") {
+        console.error(`chain: ${chainName}`);
+      } else {
+        console.log(`${DIM}chain: ${chainName}${RESET}
+`);
+      }
+      printResult(result, format);
     } finally {
       clientHandle.destroy();
     }
@@ -1030,7 +1080,17 @@ function registerHashCommand(cli) {
 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) => {
     const config = await loadConfig();
-    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
+    const knownChains = Object.keys(config.chains);
+    let effectiveChain = opts.chain;
+    let palletName;
+    let itemName;
+    if (target) {
+      const parsed = parseTarget(target, { knownChains, allowPalletOnly: true });
+      effectiveChain = resolveTargetChain(parsed, opts.chain);
+      palletName = parsed.pallet;
+      itemName = parsed.item;
+    }
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
     let meta;
     try {
       meta = await getOrFetchMetadata(chainName);
@@ -1057,11 +1117,11 @@ function registerInspectCommand(cli) {
       console.log();
       return;
     }
-    if (!target.includes(".")) {
+    if (!itemName) {
       const palletNames2 = getPalletNames(meta);
-      const pallet2 = findPallet(meta, target);
+      const pallet2 = findPallet(meta, palletName);
       if (!pallet2) {
-        throw new Error(suggestMessage("pallet", target, palletNames2));
+        throw new Error(suggestMessage("pallet", palletName, palletNames2));
       }
       printHeading(`${pallet2.name} Pallet`);
       if (pallet2.docs.length) {
@@ -1086,7 +1146,6 @@ function registerInspectCommand(cli) {
       }
       return;
     }
-    const { pallet: palletName, item: itemName } = parseTarget(target);
     const palletNames = getPalletNames(meta);
     const pallet = findPallet(meta, palletName);
     if (!pallet) {
@@ -1146,6 +1205,254 @@ function parseValue(arg) {
   return arg;
 }
 
+// src/commands/tx.ts
+import { getViewBuilder } from "@polkadot-api/view-builder";
+import { Binary } from "polkadot-api";
+
+// src/core/explorers.ts
+var pjsAppsLink = (rpc, hash) => `https://polkadot.js.org/apps/?rpc=${encodeURIComponent(rpc)}#/explorer/query/${hash}`;
+var papiLink = (rpc, hash) => `https://dev.papi.how/explorer/${hash}#networkId=custom&endpoint=${encodeURIComponent(rpc)}`;
+
+// src/commands/tx.ts
+function parseStructArgs(meta, fields, args, callLabel) {
+  const fieldNames = Object.keys(fields);
+  if (args.length !== fieldNames.length) {
+    const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
+    throw new Error(`${callLabel} takes ${fieldNames.length} argument(s): ${expected}
+` + `  Got ${args.length} argument(s).`);
+  }
+  const result = {};
+  for (let i = 0;i < fieldNames.length; i++) {
+    const name = fieldNames[i];
+    const entry = fields[name];
+    result[name] = parseTypedArg(meta, entry, args[i]);
+  }
+  return result;
+}
+function normalizeValue(lookup, entry, value) {
+  let resolved = entry;
+  while (resolved.type === "lookupEntry") {
+    resolved = resolved.value;
+  }
+  switch (resolved.type) {
+    case "enum": {
+      if (value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value) {
+        const enumValue = value;
+        const variant = resolved.value[enumValue.type];
+        if (variant) {
+          let innerEntry = variant;
+          while (innerEntry.type === "lookupEntry") {
+            innerEntry = innerEntry.value;
+          }
+          let normalizedInner = enumValue.value;
+          if (innerEntry.type !== "array" && innerEntry.type !== "sequence" && innerEntry.type !== "void" && Array.isArray(normalizedInner) && normalizedInner.length === 1) {
+            normalizedInner = normalizedInner[0];
+          }
+          if (normalizedInner !== undefined && innerEntry.type !== "void") {
+            normalizedInner = normalizeValue(lookup, innerEntry, normalizedInner);
+          }
+          return { type: enumValue.type, value: normalizedInner };
+        }
+      }
+      return value;
+    }
+    case "struct": {
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const fields = resolved.value;
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+          if (key in fields) {
+            result[key] = normalizeValue(lookup, fields[key], val);
+          } else {
+            result[key] = val;
+          }
+        }
+        return result;
+      }
+      return value;
+    }
+    case "array":
+    case "sequence": {
+      let innerResolved = resolved.value;
+      while (innerResolved.type === "lookupEntry") {
+        innerResolved = innerResolved.value;
+      }
+      if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
+        if (/^0x[0-9a-fA-F]*$/.test(value))
+          return Binary.fromHex(value);
+        return Binary.fromText(value);
+      }
+      if (Array.isArray(value)) {
+        const innerEntry = resolved.value;
+        return value.map((item) => normalizeValue(lookup, innerEntry, item));
+      }
+      return value;
+    }
+    case "tuple": {
+      if (Array.isArray(value)) {
+        const entries = resolved.value;
+        return value.map((item, i) => i < entries.length ? normalizeValue(lookup, entries[i], item) : item);
+      }
+      return value;
+    }
+    case "option": {
+      if (value !== null && value !== undefined) {
+        return normalizeValue(lookup, resolved.value, value);
+      }
+      return;
+    }
+    case "primitive": {
+      if (typeof value === "string") {
+        const prim = resolved.value;
+        switch (prim) {
+          case "bool":
+            return value === "true";
+          case "u64":
+          case "u128":
+          case "u256":
+          case "i64":
+          case "i128":
+          case "i256":
+            return BigInt(value);
+          case "u8":
+          case "u16":
+          case "u32":
+          case "i8":
+          case "i16":
+          case "i32":
+            return parseInt(value, 10);
+        }
+      }
+      return value;
+    }
+    case "compact": {
+      if (typeof value === "string") {
+        return resolved.isBig ? BigInt(value) : parseInt(value, 10);
+      }
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+function parseTypedArg(meta, entry, arg) {
+  switch (entry.type) {
+    case "primitive":
+      return parsePrimitive(entry.value, arg);
+    case "compact":
+      return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
+    case "AccountId32":
+    case "AccountId20":
+      return arg;
+    case "option": {
+      if (arg === "null" || arg === "undefined" || arg === "none") {
+        return;
+      }
+      return parseTypedArg(meta, entry.value, arg);
+    }
+    case "enum": {
+      if (/^0x[0-9a-fA-F]+$/.test(arg) && meta.lookup.call != null && entry.id === meta.lookup.call) {
+        const callCodec = meta.builder.buildDefinition(meta.lookup.call);
+        return callCodec.dec(Binary.fromHex(arg).asBytes());
+      }
+      if (arg.startsWith("{")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      const variants = Object.keys(entry.value);
+      if (variants.includes("Id")) {
+        const idVariant = entry.value.Id;
+        const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
+        if (innerType.type === "AccountId32" && !arg.startsWith("{")) {
+          return { type: "Id", value: arg };
+        }
+      }
+      const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());
+      if (matched) {
+        const variant = entry.value[matched];
+        if (variant.type === "void") {
+          return { type: matched };
+        }
+      }
+      return parseValue(arg);
+    }
+    case "sequence":
+    case "array": {
+      const inner = entry.value;
+      if (inner.type === "primitive" && inner.value === "u8") {
+        if (/^0x[0-9a-fA-F]*$/.test(arg))
+          return Binary.fromHex(arg);
+        return Binary.fromText(arg);
+      }
+      if (arg.startsWith("[")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      if (/^0x[0-9a-fA-F]*$/.test(arg))
+        return Binary.fromHex(arg);
+      return parseValue(arg);
+    }
+    case "struct":
+      if (arg.startsWith("{")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      return parseValue(arg);
+    case "tuple":
+      if (arg.startsWith("[")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      return parseValue(arg);
+    default:
+      return parseValue(arg);
+  }
+}
+function parsePrimitive(prim, arg) {
+  switch (prim) {
+    case "bool":
+      return arg === "true";
+    case "char":
+    case "str":
+      return arg;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i8":
+    case "i16":
+    case "i32":
+      return parseInt(arg, 10);
+    case "u64":
+    case "u128":
+    case "u256":
+    case "i64":
+    case "i128":
+    case "i256":
+      return BigInt(arg);
+    default:
+      return parseValue(arg);
+  }
+}
+var PAPI_BUILTIN_EXTENSIONS = new Set([
+  "CheckNonZeroSender",
+  "CheckSpecVersion",
+  "CheckTxVersion",
+  "CheckGenesis",
+  "CheckMortality",
+  "CheckNonce",
+  "CheckWeight",
+  "ChargeTransactionPayment",
+  "ChargeAssetTxPayment",
+  "CheckMetadataHash",
+  "StorageWeightReclaim",
+  "PrevalidateAttests"
+]);
+var NO_DEFAULT = Symbol("no-default");
+
 // src/commands/query.ts
 var DEFAULT_LIMIT = 100;
 function registerQueryCommand(cli) {
@@ -1153,7 +1460,7 @@ function registerQueryCommand(cli) {
     default: DEFAULT_LIMIT
   }).action(async (target, keys, opts) => {
     if (!target) {
-      console.log("Usage: dot query <Pallet.Item> [...keys] [--chain <name>] [--output json]");
+      console.log("Usage: dot query <[Chain.]Pallet.Item> [...keys] [--chain <name>] [--output json]");
       console.log("");
       console.log("Examples:");
       console.log("  $ dot query System.Number                         # plain storage value");
@@ -1162,11 +1469,16 @@ function registerQueryCommand(cli) {
       console.log("  $ dot query System.Account --limit 10             # first 10 entries");
       console.log("  $ dot query System.Account --limit 0              # all entries (no limit)");
       console.log("  $ dot query Assets.Metadata 42 --chain asset-hub");
+      console.log("  $ dot query kusama.System.Account 5Grw...         # chain prefix");
       return;
     }
     const config = await loadConfig();
-    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
-    const { pallet, item } = parseTarget(target);
+    const knownChains = Object.keys(config.chains);
+    const parsed = parseTarget(target, { knownChains });
+    const effectiveChain = resolveTargetChain(parsed, opts.chain);
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
+    const pallet = parsed.pallet;
+    const item = parsed.item;
     const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
     try {
       const meta = await getOrFetchMetadata(chainName, clientHandle);
@@ -1182,8 +1494,14 @@ function registerQueryCommand(cli) {
       }
       const unsafeApi = clientHandle.client.getUnsafeApi();
       const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
-      const parsedKeys = keys.map(parseValue);
+      const parsedKeys = parseStorageKeys(meta, palletInfo.name, storageItem, keys);
       const format = opts.output ?? "pretty";
+      if (format === "json") {
+        console.error(`chain: ${chainName}`);
+      } else {
+        console.log(`${DIM}chain: ${chainName}${RESET}
+`);
+      }
       if (storageItem.type === "map" && parsedKeys.length === 0) {
         const entries = await storageApi.getEntries();
         const limit = Number(opts.limit);
@@ -1206,26 +1524,57 @@ ${DIM}Showing ${limit} of ${entries.length} entries. Use --limit 0 for all.${RES
     }
   });
 }
+function parseStorageKeys(meta, palletName, storageItem, args) {
+  if (storageItem.type === "plain" || storageItem.keyTypeId == null) {
+    return args.map(parseValue);
+  }
+  if (args.length === 0)
+    return [];
+  const storageEntry = meta.builder.buildStorage(palletName, storageItem.name);
+  const len = storageEntry.len;
+  const keyEntry = meta.lookup(storageItem.keyTypeId);
+  if (len === 1) {
+    if (args.length === 1) {
+      return [parseTypedArg(meta, keyEntry, args[0])];
+    }
+    if (keyEntry.type === "struct") {
+      const label = `${palletName}.${storageItem.name} key`;
+      return [parseStructArgs(meta, keyEntry.value, args, label)];
+    }
+    const typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
+    throw new Error(`${palletName}.${storageItem.name} key expects ${typeDesc}
+` + `  Pass 1 argument. Got ${args.length}.`);
+  }
+  if (args.length !== len) {
+    let typeDesc;
+    if (keyEntry.type === "tuple") {
+      typeDesc = keyEntry.value.map((e) => describeType(meta.lookup, e.id)).join(", ");
+    } else {
+      typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
+    }
+    throw new Error(`${palletName}.${storageItem.name} expects ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
+  }
+  if (keyEntry.type === "tuple") {
+    const entries = keyEntry.value;
+    return entries.map((entry, i) => parseTypedArg(meta, entry, args[i]));
+  }
+  return args.map((arg) => parseTypedArg(meta, keyEntry, arg));
+}
 
 // src/commands/tx.ts
-import { getViewBuilder } from "@polkadot-api/view-builder";
-import { Binary } from "polkadot-api";
-
-// src/core/explorers.ts
-var pjsAppsLink = (rpc, hash) => `https://polkadot.js.org/apps/?rpc=${encodeURIComponent(rpc)}#/explorer/query/${hash}`;
-var papiLink = (rpc, hash) => `https://dev.papi.how/explorer/${hash}#networkId=custom&endpoint=${encodeURIComponent(rpc)}`;
-
-// src/commands/tx.ts
+import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
+import { Binary as Binary2 } from "polkadot-api";
 function registerTxCommand(cli) {
   cli.command("tx [target] [...args]", "Submit an extrinsic (e.g. Balances.transferKeepAlive <dest> <amount>)").option("--from <name>", "Account to sign with (required)").option("--dry-run", "Estimate fees without submitting").option("--encode", "Encode call to hex without signing or submitting").option("--ext <json>", `Custom signed extension values as JSON, e.g. '{"ExtName":{"value":...}}'`).action(async (target, args, opts) => {
     if (!target) {
-      console.log("Usage: dot tx <Pallet.Call|0xCallHex> [...args] --from <account> [--dry-run] [--encode]");
+      console.log("Usage: dot tx <[Chain.]Pallet.Call|0xCallHex> [...args] --from <account> [--dry-run] [--encode]");
       console.log("");
       console.log("Examples:");
       console.log("  $ dot tx Balances.transferKeepAlive 5FHn... 1000000000000 --from alice");
       console.log("  $ dot tx System.remark 0xdeadbeef --from alice --dry-run");
       console.log("  $ dot tx 0x0001076465616462656566 --from alice");
       console.log("  $ dot tx Assets.force_create 4 owner true 10 --encode --chain people");
+      console.log("  $ dot tx kusama.Balances.transferKeepAlive 5FHn... 1000000000000 --from alice");
       return;
     }
     if (!opts.from && !opts.encode) {
@@ -1239,7 +1588,14 @@ function registerTxCommand(cli) {
       throw new Error("--encode cannot be used with raw call hex (already encoded)");
     }
     const config = await loadConfig();
-    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
+    let effectiveChain = opts.chain;
+    let parsedTarget;
+    if (!isRawCall) {
+      const knownChains = Object.keys(config.chains);
+      parsedTarget = parseTarget(target, { knownChains });
+      effectiveChain = resolveTargetChain(parsedTarget, opts.chain);
+    }
+    const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
     const signer = opts.encode ? undefined : await resolveAccountSigner(opts.from);
     let clientHandle;
     if (!opts.encode) {
@@ -1272,11 +1628,12 @@ function registerTxCommand(cli) {
           throw new Error(`Extra arguments are not allowed when submitting a raw call hex.
 ` + "Usage: dot tx 0x<call_hex> --from <account>");
         }
-        const callBinary = Binary.fromHex(target);
+        const callBinary = Binary2.fromHex(target);
         tx = await unsafeApi.txFromCallData(callBinary);
         callHex = target;
       } else {
-        const { pallet, item: callName } = parseTarget(target);
+        const pallet = parsedTarget.pallet;
+        const callName = parsedTarget.item;
         const palletNames = getPalletNames(meta);
         const palletInfo = findPallet(meta, pallet);
         if (!palletInfo) {
@@ -1292,7 +1649,7 @@ function registerTxCommand(cli) {
           const { codec, location } = meta.builder.buildCall(palletInfo.name, callInfo.name);
           const encodedArgs = codec.enc(callData);
           const fullCall = new Uint8Array([location[0], location[1], ...encodedArgs]);
-          console.log(Binary.fromBytes(fullCall).asHex());
+          console.log(Binary2.fromBytes(fullCall).asHex());
           return;
         }
         tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
@@ -1377,7 +1734,7 @@ function formatDispatchError(err) {
 }
 function decodeCall(meta, callHex) {
   try {
-    const viewBuilder = getViewBuilder(meta.lookup);
+    const viewBuilder = getViewBuilder2(meta.lookup);
     const decoded = viewBuilder.callDecoder(callHex);
     const palletName = decoded.pallet.value.name;
     const callName = decoded.call.value.name;
@@ -1494,30 +1851,30 @@ function parseCallArgs(meta, palletName, callName, args) {
     return;
   }
   if (variant.type === "struct") {
-    return parseStructArgs(meta, variant.value, args, `${palletName}.${callName}`);
+    return parseStructArgs2(meta, variant.value, args, `${palletName}.${callName}`);
   }
   if (variant.type === "lookupEntry") {
     const inner = variant.value;
     if (inner.type === "struct") {
-      return parseStructArgs(meta, inner.value, args, `${palletName}.${callName}`);
+      return parseStructArgs2(meta, inner.value, args, `${palletName}.${callName}`);
     }
     if (inner.type === "void")
       return;
     if (args.length !== 1) {
       throw new Error(`${palletName}.${callName} takes 1 argument (${describeType(meta.lookup, inner.id)}), but ${args.length} provided.`);
     }
-    return parseTypedArg(meta, inner, args[0]);
+    return parseTypedArg2(meta, inner, args[0]);
   }
   if (variant.type === "tuple") {
     const entries = variant.value;
     if (args.length !== entries.length) {
       throw new Error(`${palletName}.${callName} takes ${entries.length} arguments, but ${args.length} provided.`);
     }
-    return entries.map((entry, i) => parseTypedArg(meta, entry, args[i]));
+    return entries.map((entry, i) => parseTypedArg2(meta, entry, args[i]));
   }
   return args.length === 0 ? undefined : args.map(parseValue);
 }
-function parseStructArgs(meta, fields, args, callLabel) {
+function parseStructArgs2(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
     const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
@@ -1528,11 +1885,11 @@ function parseStructArgs(meta, fields, args, callLabel) {
   for (let i = 0;i < fieldNames.length; i++) {
     const name = fieldNames[i];
     const entry = fields[name];
-    result[name] = parseTypedArg(meta, entry, args[i]);
+    result[name] = parseTypedArg2(meta, entry, args[i]);
   }
   return result;
 }
-function normalizeValue(lookup, entry, value) {
+function normalizeValue2(lookup, entry, value) {
   let resolved = entry;
   while (resolved.type === "lookupEntry") {
     resolved = resolved.value;
@@ -1552,7 +1909,7 @@ function normalizeValue(lookup, entry, value) {
             normalizedInner = normalizedInner[0];
           }
           if (normalizedInner !== undefined && innerEntry.type !== "void") {
-            normalizedInner = normalizeValue(lookup, innerEntry, normalizedInner);
+            normalizedInner = normalizeValue2(lookup, innerEntry, normalizedInner);
           }
           return { type: enumValue.type, value: normalizedInner };
         }
@@ -1565,7 +1922,7 @@ function normalizeValue(lookup, entry, value) {
         const result = {};
         for (const [key, val] of Object.entries(value)) {
           if (key in fields) {
-            result[key] = normalizeValue(lookup, fields[key], val);
+            result[key] = normalizeValue2(lookup, fields[key], val);
           } else {
             result[key] = val;
           }
@@ -1582,25 +1939,25 @@ function normalizeValue(lookup, entry, value) {
       }
       if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
         if (/^0x[0-9a-fA-F]*$/.test(value))
-          return Binary.fromHex(value);
-        return Binary.fromText(value);
+          return Binary2.fromHex(value);
+        return Binary2.fromText(value);
       }
       if (Array.isArray(value)) {
         const innerEntry = resolved.value;
-        return value.map((item) => normalizeValue(lookup, innerEntry, item));
+        return value.map((item) => normalizeValue2(lookup, innerEntry, item));
       }
       return value;
     }
     case "tuple": {
       if (Array.isArray(value)) {
         const entries = resolved.value;
-        return value.map((item, i) => i < entries.length ? normalizeValue(lookup, entries[i], item) : item);
+        return value.map((item, i) => i < entries.length ? normalizeValue2(lookup, entries[i], item) : item);
       }
       return value;
     }
     case "option": {
       if (value !== null && value !== undefined) {
-        return normalizeValue(lookup, resolved.value, value);
+        return normalizeValue2(lookup, resolved.value, value);
       }
       return;
     }
@@ -1638,10 +1995,10 @@ function normalizeValue(lookup, entry, value) {
       return value;
   }
 }
-function parseTypedArg(meta, entry, arg) {
+function parseTypedArg2(meta, entry, arg) {
   switch (entry.type) {
     case "primitive":
-      return parsePrimitive(entry.value, arg);
+      return parsePrimitive2(entry.value, arg);
     case "compact":
       return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
     case "AccountId32":
@@ -1651,16 +2008,16 @@ function parseTypedArg(meta, entry, arg) {
       if (arg === "null" || arg === "undefined" || arg === "none") {
         return;
       }
-      return parseTypedArg(meta, entry.value, arg);
+      return parseTypedArg2(meta, entry.value, arg);
     }
     case "enum": {
       if (/^0x[0-9a-fA-F]+$/.test(arg) && meta.lookup.call != null && entry.id === meta.lookup.call) {
         const callCodec = meta.builder.buildDefinition(meta.lookup.call);
-        return callCodec.dec(Binary.fromHex(arg).asBytes());
+        return callCodec.dec(Binary2.fromHex(arg).asBytes());
       }
       if (arg.startsWith("{")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       const variants = Object.keys(entry.value);
@@ -1685,29 +2042,29 @@ function parseTypedArg(meta, entry, arg) {
       const inner = entry.value;
       if (inner.type === "primitive" && inner.value === "u8") {
         if (/^0x[0-9a-fA-F]*$/.test(arg))
-          return Binary.fromHex(arg);
-        return Binary.fromText(arg);
+          return Binary2.fromHex(arg);
+        return Binary2.fromText(arg);
       }
       if (arg.startsWith("[")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       if (/^0x[0-9a-fA-F]*$/.test(arg))
-        return Binary.fromHex(arg);
+        return Binary2.fromHex(arg);
       return parseValue(arg);
     }
     case "struct":
       if (arg.startsWith("{")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       return parseValue(arg);
     case "tuple":
       if (arg.startsWith("[")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       return parseValue(arg);
@@ -1715,7 +2072,7 @@ function parseTypedArg(meta, entry, arg) {
       return parseValue(arg);
   }
 }
-function parsePrimitive(prim, arg) {
+function parsePrimitive2(prim, arg) {
   switch (prim) {
     case "bool":
       return arg === "true";
@@ -1740,7 +2097,7 @@ function parsePrimitive(prim, arg) {
       return parseValue(arg);
   }
 }
-var PAPI_BUILTIN_EXTENSIONS = new Set([
+var PAPI_BUILTIN_EXTENSIONS2 = new Set([
   "CheckNonZeroSender",
   "CheckSpecVersion",
   "CheckTxVersion",
@@ -1770,12 +2127,12 @@ function parseExtOption(ext) {
 ` + `Expected format: '{"ExtName":{"value":...}}'`);
   }
 }
-var NO_DEFAULT = Symbol("no-default");
+var NO_DEFAULT2 = Symbol("no-default");
 function buildCustomSignedExtensions(meta, userOverrides) {
   const result = {};
   const extensions = getSignedExtensions(meta);
   for (const ext of extensions) {
-    if (PAPI_BUILTIN_EXTENSIONS.has(ext.identifier))
+    if (PAPI_BUILTIN_EXTENSIONS2.has(ext.identifier))
       continue;
     if (ext.identifier in userOverrides) {
       result[ext.identifier] = userOverrides[ext.identifier];
@@ -1785,10 +2142,10 @@ function buildCustomSignedExtensions(meta, userOverrides) {
     const addEntry = meta.lookup(ext.additionalSigned);
     const value = autoDefaultForType(valueEntry);
     const add = autoDefaultForType(addEntry);
-    if (value !== NO_DEFAULT || add !== NO_DEFAULT) {
+    if (value !== NO_DEFAULT2 || add !== NO_DEFAULT2) {
       result[ext.identifier] = {
-        ...value !== NO_DEFAULT ? { value } : {},
-        ...add !== NO_DEFAULT ? { additionalSigned: add } : {}
+        ...value !== NO_DEFAULT2 ? { value } : {},
+        ...add !== NO_DEFAULT2 ? { additionalSigned: add } : {}
       };
     }
   }
@@ -1805,7 +2162,7 @@ function autoDefaultForType(entry) {
       return { type: "Disabled", value: undefined };
     }
   }
-  return NO_DEFAULT;
+  return NO_DEFAULT2;
 }
 function watchTransaction(observable) {
   const spinner = new Spinner;
@@ -1845,6 +2202,110 @@ function watchTransaction(observable) {
   });
 }
 
+// src/core/update-notifier.ts
+import { readFileSync } from "node:fs";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var CACHE_FILE = "update-check.json";
+var STALE_MS = 24 * 60 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 5000;
+var REGISTRY_URL = "https://registry.npmjs.org/polkadot-cli/latest";
+function parseSemver(v) {
+  const clean = v.replace(/^v/, "").split("-")[0] ?? v;
+  const parts = clean.split(".").map(Number);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0;i < 3; i++) {
+    const left = pa[i] ?? 0;
+    const right = pb[i] ?? 0;
+    if (left < right)
+      return -1;
+    if (left > right)
+      return 1;
+  }
+  return 0;
+}
+function isNewerVersion(current, latest) {
+  return compareSemver(current, latest) < 0;
+}
+function buildNotificationBox(current, latest) {
+  const YELLOW2 = "\x1B[33m";
+  const GREEN2 = "\x1B[32m";
+  const CYAN2 = "\x1B[36m";
+  const RESET2 = "\x1B[0m";
+  const BOLD2 = "\x1B[1m";
+  const line1 = `Update available! ${YELLOW2}${current}${RESET2} → ${GREEN2}${BOLD2}${latest}${RESET2}`;
+  const line2 = `Run ${CYAN2}npm i -g polkadot-cli${RESET2} to update`;
+  const visibleLine1 = `Update available! ${current} → ${latest}`;
+  const visibleLine2 = `Run npm i -g polkadot-cli to update`;
+  const innerWidth = Math.max(visibleLine1.length, visibleLine2.length) + 4;
+  const pad1 = " ".repeat(innerWidth - visibleLine1.length - 4);
+  const pad2 = " ".repeat(innerWidth - visibleLine2.length - 4);
+  const empty = " ".repeat(innerWidth);
+  const top = `╭${"─".repeat(innerWidth)}╮`;
+  const bot = `╰${"─".repeat(innerWidth)}╯`;
+  return [
+    top,
+    `│${empty}│`,
+    `│  ${line1}${pad1}  │`,
+    `│  ${line2}${pad2}  │`,
+    `│${empty}│`,
+    bot
+  ].join(`
+`);
+}
+function getCachePath() {
+  return join3(getConfigDir(), CACHE_FILE);
+}
+function readCache() {
+  try {
+    const data = readFileSync(getCachePath(), "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+async function writeCache(cache) {
+  try {
+    await mkdir3(getConfigDir(), { recursive: true });
+    await writeFile3(getCachePath(), `${JSON.stringify(cache)}
+`);
+  } catch {}
+}
+function startBackgroundCheck(_currentVersion) {
+  const cache = readCache();
+  const now = Date.now();
+  if (cache && now - cache.lastCheck < STALE_MS) {
+    return;
+  }
+  fetch(REGISTRY_URL, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  }).then((res) => res.json()).then((data) => {
+    const latestVersion = data.version;
+    if (typeof latestVersion === "string") {
+      writeCache({ lastCheck: now, latestVersion });
+    }
+  }).catch(() => {});
+}
+function getUpdateNotification(currentVersion) {
+  if (process.env.DOT_NO_UPDATE_CHECK === "1")
+    return null;
+  if (process.env.CI)
+    return null;
+  if (!process.stderr.isTTY)
+    return null;
+  const cache = readCache();
+  if (!cache)
+    return null;
+  if (isNewerVersion(currentVersion, cache.latestVersion)) {
+    return buildNotificationBox(currentVersion, cache.latestVersion);
+  }
+  return null;
+}
+
 // src/utils/errors.ts
 class CliError2 extends Error {
   constructor(message) {
@@ -1854,6 +2315,7 @@ class CliError2 extends Error {
 }
 
 // src/cli.ts
+startBackgroundCheck(version);
 var cli = cac("dot");
 cli.option("--chain <name>", "Target chain (default from config)");
 cli.option("--rpc <url>", "Override RPC endpoint for this call");
@@ -1870,6 +2332,13 @@ registerTxCommand(cli);
 registerHashCommand(cli);
 cli.help();
 cli.version(version);
+function showUpdateAndExit(code) {
+  const note = getUpdateNotification(version);
+  if (note)
+    process.stderr.write(`${note}
+`);
+  process.exit(code);
+}
 function handleError(err) {
   if (err instanceof CliError2) {
     console.error(`Error: ${err.message}`);
@@ -1878,16 +2347,19 @@ function handleError(err) {
   } else {
     console.error("An unexpected error occurred:", err);
   }
-  process.exit(1);
+  showUpdateAndExit(1);
 }
 try {
   cli.parse(process.argv, { run: false });
-  if (!cli.matchedCommandName && !cli.options.help && !cli.options.version) {
+  if (cli.options.version || cli.options.help) {
+    showUpdateAndExit(0);
+  } else if (!cli.matchedCommandName) {
     cli.outputHelp();
+    showUpdateAndExit(0);
   } else {
     const result = cli.runMatchedCommand();
     if (result && typeof result.then === "function") {
-      result.then(() => process.exit(0), handleError);
+      result.then(() => showUpdateAndExit(0), handleError);
     }
   }
 } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-dir=coverage",
     "prepare": "husky",
     "changeset": "changeset",
     "version": "changeset version",