polkadot-cli 1.8.0 → 1.9.0

package/README.md

@@ -1,3 +1,4 @@
+[![npm version](https://img.shields.io/npm/v/polkadot-cli)](https://www.npmjs.com/package/polkadot-cli)
 [![codecov](https://codecov.io/gh/peetzweg/polkadot-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/peetzweg/polkadot-cli)
 
 # polkadot-cli
@@ -309,12 +310,32 @@ dot query System.Number --output json | jq '.+1'
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
+#### Partial key queries
+
+For storage maps with multiple keys (NMaps), you can provide fewer keys than
+expected to retrieve all entries matching that prefix. This uses the chain's
+prefix-based iteration and does not require `--dump`.
+
+```bash
+# Full key — returns a single value
+dot query Staking.ErasStakers 100 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+
+# Partial key — returns all entries matching the first key
+dot query Staking.ErasStakers 100
+
+# No keys — requires --dump (safety net for large maps)
+dot query Staking.ErasStakers --dump --limit 10
+```
+
+The `--limit` option applies to partial key results just like it does for
+`--dump` (default: 100, use `--limit 0` for unlimited).
+
 #### Output formatting
 
 Query results automatically convert on-chain types for readability:
 
 - **BigInt** values (e.g. balances) render as decimal strings
-- **Binary** fields (e.g. token `name`, `symbol`) render as text when valid UTF-8, or as `0x`-prefixed hex otherwise
+- **Binary** fields (e.g. token `name`, `symbol`) render as text when the value contains only printable characters, or as `0x`-prefixed hex otherwise (values containing control characters, Private Use Area code points, or invalid UTF-8 sequences always fall back to hex)
 - **Uint8Array** values render as `0x`-prefixed hex
 
 ```bash
@@ -773,6 +794,14 @@ tx:
       value: ${AMOUNT}
 ```
 
+Hex values passed via `--var` are preserved as-is, including leading zeros. This is important for encoded call data in XCM `Transact` instructions or similar byte-array fields:
+
+```bash
+# Encode a remark, then embed it in an XCM Transact via --var
+CALL=$(dot tx.System.remark 0xdead --encode)
+dot ./xcm-transact.yaml --var CALL=$CALL --encode
+```
+
 All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--yaml`, `--json`, `--output`, etc. behave identically to inline commands.
 
 ### Compute hashes

package/dist/cli.mjs

@@ -387,14 +387,35 @@ var init_accounts = __esm(() => {
   DEV_NAMES = ["alice", "bob", "charlie", "dave", "eve", "ferdie"];
 });
 
+// src/utils/binary-display.ts
+function isReadableText(text) {
+  for (let i = 0;i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code <= 31 && code !== 9 && code !== 10 && code !== 13)
+      return false;
+    if (code === 127)
+      return false;
+    if (code >= 128 && code <= 159)
+      return false;
+    if (code === 65533)
+      return false;
+    if (code >= 57344 && code <= 63743)
+      return false;
+  }
+  return true;
+}
+function binaryToDisplay(value) {
+  const text = value.asText();
+  return isReadableText(text) ? text : value.asHex();
+}
+
 // src/core/output.ts
 import { Binary } from "polkadot-api";
 function replacer(_key, value) {
   if (typeof value === "bigint")
     return value.toString();
   if (value instanceof Binary) {
-    const text = value.asText();
-    return text.includes("�") ? value.asHex() : text;
+    return binaryToDisplay(value);
   }
   if (value instanceof Uint8Array)
     return `0x${Buffer.from(value).toString("hex")}`;
@@ -2158,7 +2179,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.8.0";
+var version = "1.9.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -3440,6 +3461,7 @@ async function showItemHelp2(category, target, opts) {
 init_hash();
 init_output();
 init_errors();
+import { readFile as readFile3 } from "node:fs/promises";
 async function resolveInput(data, opts) {
   const sources = [data !== undefined, !!opts.file, !!opts.stdin].filter(Boolean).length;
   if (sources > 1) {
@@ -3449,26 +3471,15 @@ async function resolveInput(data, opts) {
     throw new CliError("No input provided. Pass data as argument, or use --file or --stdin");
   }
   if (opts.file) {
-    const buf = await Bun.file(opts.file).arrayBuffer();
+    const buf = await readFile3(opts.file);
     return new Uint8Array(buf);
   }
   if (opts.stdin) {
-    const reader = Bun.stdin.stream().getReader();
     const chunks = [];
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      chunks.push(value);
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
     }
-    const totalLen = chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(totalLen);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return result;
+    return new Uint8Array(Buffer.concat(chunks));
   }
   return parseInputData(data);
 }
@@ -3937,14 +3948,15 @@ async function handleQuery(target, keys, opts) {
     ];
     const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, effectiveKeys);
     const format = opts.output ?? "pretty";
-    if (storageItem.type === "map" && parsedKeys.length === 0) {
-      if (!opts.dump) {
+    const expectedLen = storageItem.type === "map" && storageItem.keyTypeId != null ? meta.builder.buildStorage(palletInfo.name, storageItem.name).len : 0;
+    if (storageItem.type === "map" && parsedKeys.length < expectedLen) {
+      if (parsedKeys.length === 0 && !opts.dump) {
         clientHandle.destroy();
         await showItemHelp("query", target, { chain: opts.chain, rpc: opts.rpc });
         console.log(`${DIM}Hint: use --dump to fetch all entries${RESET}`);
         return;
       }
-      const entries = await storageApi.getEntries();
+      const entries = await storageApi.getEntries(...parsedKeys);
       const limit = Number(opts.limit);
       const truncated = limit > 0 && entries.length > limit;
       const display = truncated ? entries.slice(0, limit) : entries;
@@ -3988,18 +4000,18 @@ async function parseStorageKeys(meta, palletName2, storageItem, args) {
     throw new Error(`${palletName2}.${storageItem.name} key expects ${typeDesc}
 ` + `  Pass 1 argument. Got ${args.length}.`);
   }
-  if (args.length !== len) {
+  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(`${palletName2}.${storageItem.name} expects ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
+    throw new Error(`${palletName2}.${storageItem.name} expects at most ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
   }
   if (keyEntry.type === "tuple") {
     const entries = keyEntry.value;
-    return Promise.all(entries.map((entry, i) => parseTypedArg(meta, entry, args[i])));
+    return Promise.all(entries.slice(0, args.length).map((entry, i) => parseTypedArg(meta, entry, args[i])));
   }
   return Promise.all(args.map((arg) => parseTypedArg(meta, keyEntry, arg)));
 }
@@ -4462,8 +4474,7 @@ function formatEventValue(v) {
   if (v === null || v === undefined)
     return "null";
   if (v instanceof Binary3) {
-    const text = v.asText();
-    return text.includes("�") ? v.asHex() : text;
+    return binaryToDisplay(v);
   }
   return JSON.stringify(v, (_k, val) => typeof val === "bigint" ? val.toString() : val);
 }
@@ -4958,7 +4969,7 @@ function watchTransaction(observable, level) {
 
 // src/config/store.ts
 init_types();
-import { access as access3, mkdir as mkdir3, readFile as readFile3, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
+import { access as access3, mkdir as mkdir3, readFile as readFile4, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import { join as join3 } from "node:path";
 var DOT_DIR2 = join3(homedir2(), ".polkadot");
@@ -4978,7 +4989,7 @@ async function fileExists3(path) {
 async function loadConfig2() {
   await ensureDir3(DOT_DIR2);
   if (await fileExists3(CONFIG_PATH2)) {
-    const saved = JSON.parse(await readFile3(CONFIG_PATH2, "utf-8"));
+    const saved = JSON.parse(await readFile4(CONFIG_PATH2, "utf-8"));
     return {
       ...saved,
       chains: { ...DEFAULT_CONFIG.chains, ...saved.chains }
@@ -4995,6 +5006,7 @@ async function saveConfig2(config) {
 
 // src/core/file-loader.ts
 init_errors();
+import { access as access4, readFile as readFile5 } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 var CATEGORIES = ["tx", "query", "const", "apis"];
 var FILE_EXTENSIONS = [".json", ".yaml", ".yml"];
@@ -5042,16 +5054,24 @@ function substituteVars(text, vars) {
       return envVal;
     if (defaultValue !== undefined)
       return defaultValue;
-    throw new CliError(`Undefined variable "\${${varName}}" in file. ` + `Provide it via --var ${varName}=VALUE, as an environment variable, ` + `or add a default with \${${varName}:-default}.`);
+    throw new CliError(`Undefined variable "\${${varName}}" in file.
+
+` + `  Provide it using one of:
+` + `    --var ${varName}=VALUE
+` + `    ${varName}=VALUE dot ...    (environment variable)
+` + `    \${${varName}:-default}     (inline default in file)`);
   });
 }
+function quoteYamlHexValues(text) {
+  return text.replace(/^(\s*(?:[^:]+:\s+|-\s+))(0x[0-9a-fA-F]+)\s*$/gm, '$1"$2"');
+}
 async function loadCommandFile(filePath, cliVars) {
-  const file = Bun.file(filePath);
-  const exists = await file.exists();
-  if (!exists) {
+  try {
+    await access4(filePath);
+  } catch {
     throw new CliError(`File not found: ${filePath}`);
   }
-  const rawText = await file.text();
+  const rawText = await readFile5(filePath, "utf-8");
   if (!rawText.trim()) {
     throw new CliError(`File is empty: ${filePath}`);
   }
@@ -5070,9 +5090,10 @@ async function loadCommandFile(filePath, cliVars) {
   } catch {}
   const mergedVars = { ...fileVars, ...cliVars };
   const substituted = substituteVars(rawText, mergedVars);
+  const textToParse = isJson ? substituted : quoteYamlHexValues(substituted);
   let parsed;
   try {
-    parsed = isJson ? JSON.parse(substituted) : parseYaml(substituted);
+    parsed = isJson ? JSON.parse(textToParse) : parseYaml(textToParse);
   } catch (err) {
     const format = isJson ? "JSON" : "YAML";
     const msg = err instanceof Error ? err.message : String(err);

package/package.json

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