polkadot-cli 0.7.0 → 0.8.1

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.
@@ -66,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,8 +94,12 @@ dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 # All map entries (default limit: 100)
 dot query System.Account --limit 10
 
-# Pipe to jq (colors disabled automatically)
+# Pipe to jq — stdout is clean JSON, no extra text
 dot query System.Account --limit 5 | jq '.[0].value.data.free'
+dot query System.Number --output json | jq '.+1'
+
+# Query a specific chain using chain prefix
+dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
 ### Look up constants
@@ -87,6 +107,10 @@ 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
+
+# Pipe to jq — stdout is clean JSON, no extra text
+dot const Balances.ExistentialDeposit --output json | jq
 ```
 
 ### Inspect metadata
@@ -102,6 +126,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

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.7.0";
+var version = "0.8.1";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -848,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);
@@ -886,7 +931,8 @@ 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";
+      printResult(result, format);
     } finally {
       clientHandle.destroy();
     }
@@ -1028,7 +1074,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);
@@ -1055,11 +1111,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) {
@@ -1084,7 +1140,6 @@ function registerInspectCommand(cli) {
       }
       return;
     }
-    const { pallet: palletName, item: itemName } = parseTarget(target);
     const palletNames = getPalletNames(meta);
     const pallet = findPallet(meta, palletName);
     if (!pallet) {
@@ -1399,7 +1454,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");
@@ -1408,11 +1463,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);
@@ -1430,12 +1490,6 @@ function registerQueryCommand(cli) {
       const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
       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);
@@ -1501,13 +1555,14 @@ 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) {
@@ -1521,7 +1576,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) {
@@ -1558,7 +1620,8 @@ function registerTxCommand(cli) {
         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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "test": "bun test",
+    "test": "bun test --concurrent",
+    "test:coverage": "bun test --concurrent --coverage --coverage-reporter=lcov --coverage-dir=coverage",
     "prepare": "husky",
     "changeset": "changeset",
     "version": "changeset version",