polkadot-cli 1.6.1 → 1.7.0

package/README.md

@@ -20,6 +20,7 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ Named address resolution across all commands
 - ✅ Runtime API calls — `dot apis.Core.version`
 - ✅ Batteries included — all system parachains and testnets already setup to be used
+- ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
 
 ### Preconfigured chains
 
@@ -572,6 +573,185 @@ For manual override, use `--ext` with a JSON object:
 dot tx System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"..."}}'
 ```
 
+### File-based commands
+
+Run any `dot` command from a YAML or JSON file. Especially useful for complex calls like XCM messages that are hard to construct inline.
+
+**Teleport DOT** from Asset Hub to the relay chain:
+
+```yaml
+# teleport-dot.xcm.yaml
+chain: polkadot-asset-hub
+tx:
+  PolkadotXcm:
+    limited_teleport_assets:
+      dest:
+        type: V4
+        value:
+          parents: 1
+          interior:
+            type: Here
+      beneficiary:
+        type: V4
+        value:
+          parents: 0
+          interior:
+            type: X1
+            value:
+              - type: AccountId32
+                value:
+                  network: null
+                  id: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"
+      assets:
+        type: V4
+        value:
+          - id:
+              parents: 1
+              interior:
+                type: Here
+            fun:
+              type: Fungible
+              value: 10000000000
+      fee_asset_item: 0
+      weight_limit:
+        type: Unlimited
+```
+
+**Reserve transfer USDC** (asset 1337, 6 decimals) from Asset Hub to Hydration:
+
+```yaml
+# reserve-transfer-usdc.xcm.yaml
+chain: polkadot-asset-hub
+tx:
+  PolkadotXcm:
+    limited_reserve_transfer_assets:
+      dest:
+        type: V4
+        value:
+          parents: 1
+          interior:
+            type: X1
+            value:
+              - type: Parachain
+                value: 2034
+      beneficiary:
+        type: V4
+        value:
+          parents: 0
+          interior:
+            type: X1
+            value:
+              - type: AccountId32
+                value:
+                  network: null
+                  id: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d"
+      assets:
+        type: V4
+        value:
+          - id:
+              parents: 0
+              interior:
+                type: X2
+                value:
+                  - type: PalletInstance
+                    value: 50
+                  - type: GeneralIndex
+                    value: 1337
+            fun:
+              type: Fungible
+              value: 10000000
+      fee_asset_item: 0
+      weight_limit:
+        type: Unlimited
+```
+
+The same teleport in JSON:
+
+```json
+{
+  "chain": "polkadot-asset-hub",
+  "tx": {
+    "PolkadotXcm": {
+      "limited_teleport_assets": {
+        "dest": { "type": "V4", "value": { "parents": 1, "interior": { "type": "Here" } } },
+        "beneficiary": {
+          "type": "V4",
+          "value": {
+            "parents": 0,
+            "interior": {
+              "type": "X1",
+              "value": [{ "type": "AccountId32", "value": { "network": null, "id": "0xd435...a27d" } }]
+            }
+          }
+        },
+        "assets": {
+          "type": "V4",
+          "value": [{
+            "id": { "parents": 1, "interior": { "type": "Here" } },
+            "fun": { "type": "Fungible", "value": 10000000000 }
+          }]
+        },
+        "fee_asset_item": 0,
+        "weight_limit": { "type": "Unlimited" }
+      }
+    }
+  }
+}
+```
+
+```bash
+# Run from file
+dot ./teleport-dot.xcm.yaml --from alice --dry-run
+
+# Encode only
+dot ./reserve-transfer-usdc.xcm.yaml --encode
+
+# Override variables
+dot ./transfer.xcm.yaml --var AMOUNT=2000000000000 --from alice
+```
+
+The file format uses a required category wrapper (`tx`, `query`, `const`, or `apis`) with the structure `category > Pallet > Item > args`:
+
+```yaml
+# Simple transaction
+tx:
+  System:
+    remark:
+      - "0xdeadbeef"
+```
+
+```yaml
+# Storage query
+chain: polkadot
+query:
+  System:
+    Account:
+      - "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+```
+
+```yaml
+# Constant lookup
+chain: polkadot
+const:
+  Balances:
+    ExistentialDeposit:
+```
+
+**Variable substitution** uses shell-style `${VAR}` with optional defaults `${VAR:-default}`. Variables are resolved in order: `--var` flags > environment variables > `vars:` section defaults.
+
+```yaml
+chain: ${CHAIN:-polkadot}
+vars:
+  AMOUNT: "1000000000000"
+tx:
+  Balances:
+    transfer_keep_alive:
+      dest: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"
+      value: ${AMOUNT}
+```
+
+All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--output`, etc. behave identically to inline commands.
+
 ### Compute hashes
 
 Compute cryptographic hashes commonly used in Substrate. Supports BLAKE2b-256, BLAKE2b-128, Keccak-256, and SHA-256.

package/dist/cli.mjs

@@ -1080,8 +1080,8 @@ function normalizeValue(lookup, entry, value) {
       return;
     }
     case "primitive": {
+      const prim = resolved.value;
       if (typeof value === "string") {
-        const prim = resolved.value;
         switch (prim) {
           case "bool":
             return value === "true";
@@ -1101,12 +1101,26 @@ function normalizeValue(lookup, entry, value) {
             return parseInt(value, 10);
         }
       }
+      if (typeof value === "number") {
+        switch (prim) {
+          case "u64":
+          case "u128":
+          case "u256":
+          case "i64":
+          case "i128":
+          case "i256":
+            return BigInt(value);
+        }
+      }
       return value;
     }
     case "compact": {
       if (typeof value === "string") {
         return resolved.isBig ? BigInt(value) : parseInt(value, 10);
       }
+      if (typeof value === "number" && resolved.isBig) {
+        return BigInt(value);
+      }
       return value;
     }
     default:
@@ -1330,7 +1344,10 @@ async function handleApis(target, args, opts) {
       const names = api.methods.map((m) => m.name);
       throw new Error(suggestMessage(`method in ${api.name}`, methodName, names));
     }
-    const parsedArgs = await parseRuntimeApiArgs(meta, method, args);
+    const effectiveArgs = args.length > 0 || opts.parsedArgs == null ? args : Array.isArray(opts.parsedArgs) ? opts.parsedArgs.map((v) => typeof v === "object" ? JSON.stringify(v) : String(v)) : [
+      typeof opts.parsedArgs === "object" ? JSON.stringify(opts.parsedArgs) : String(opts.parsedArgs)
+    ];
+    const parsedArgs = await parseRuntimeApiArgs(meta, method, effectiveArgs);
     const unsafeApi = clientHandle.client.getUnsafeApi();
     const result = await unsafeApi.apis[api.name][method.name](...parsedArgs);
     const format = opts.output ?? "pretty";
@@ -1973,7 +1990,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
   const numComplete = completeSegments.length;
   if (numComplete === 0 && !endsWithDot) {
     const candidates = [
-      ...CATEGORIES.map((c) => `${c}.`),
+      ...CATEGORIES2.map((c) => `${c}.`),
       ...knownChains.map((c) => `${c}.`),
       ...NAMED_COMMANDS
     ];
@@ -2024,11 +2041,11 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
   if (firstIsChain) {
     const chainName = first;
     if (numComplete === 1 && endsWithDot) {
-      const candidates = CATEGORIES.map((c) => `${first}.${c}.`);
+      const candidates = CATEGORIES2.map((c) => `${first}.${c}.`);
       return filterPrefix(candidates, currentWord.slice(0, -1));
     }
     if (numComplete === 1 && !endsWithDot) {
-      const candidates = CATEGORIES.map((c) => `${first}.${c}.`);
+      const candidates = CATEGORIES2.map((c) => `${first}.${c}.`);
       return filterPrefix(candidates, currentWord);
     }
     if (numComplete === 2) {
@@ -2092,14 +2109,14 @@ async function completeApisCategory(prefix, numComplete, endsWithDot, segments,
   }
   return [];
 }
-var CATEGORIES, CATEGORY_ALIASES2, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
+var CATEGORIES2, CATEGORY_ALIASES2, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
 var init_complete = __esm(() => {
   init_accounts_store();
   init_store();
   init_accounts();
   init_hash();
   init_metadata();
-  CATEGORIES = ["query", "tx", "const", "events", "errors", "apis"];
+  CATEGORIES2 = ["query", "tx", "const", "events", "errors", "apis"];
   CATEGORY_ALIASES2 = {
     query: "query",
     tx: "tx",
@@ -2134,7 +2151,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.6.1";
+var version = "1.7.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -2621,7 +2638,10 @@ async function handleApis2(target, args, opts) {
       const names = api.methods.map((m) => m.name);
       throw new Error(suggestMessage(`method in ${api.name}`, methodName, names));
     }
-    const parsedArgs = await parseRuntimeApiArgs2(meta, method, args);
+    const effectiveArgs = args.length > 0 || opts.parsedArgs == null ? args : Array.isArray(opts.parsedArgs) ? opts.parsedArgs.map((v) => typeof v === "object" ? JSON.stringify(v) : String(v)) : [
+      typeof opts.parsedArgs === "object" ? JSON.stringify(opts.parsedArgs) : String(opts.parsedArgs)
+    ];
+    const parsedArgs = await parseRuntimeApiArgs2(meta, method, effectiveArgs);
     const unsafeApi = clientHandle.client.getUnsafeApi();
     const result = await unsafeApi.apis[api.name][method.name](...parsedArgs);
     const format = opts.output ?? "pretty";
@@ -3814,7 +3834,10 @@ async function handleQuery(target, keys, opts) {
     }
     const unsafeApi = clientHandle.client.getUnsafeApi();
     const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
-    const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, keys);
+    const effectiveKeys = keys.length > 0 || opts.parsedArgs == null ? keys : Array.isArray(opts.parsedArgs) ? opts.parsedArgs.map((v) => typeof v === "object" ? JSON.stringify(v) : String(v)) : [
+      typeof opts.parsedArgs === "object" ? JSON.stringify(opts.parsedArgs) : String(opts.parsedArgs)
+    ];
+    const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, effectiveKeys);
     const format = opts.output ?? "pretty";
     if (storageItem.type === "map" && parsedKeys.length === 0) {
       if (!opts.dump) {
@@ -4014,7 +4037,8 @@ async function handleTx(target, args, opts) {
         const callNames = palletInfo.calls.map((c) => c.name);
         throw new Error(suggestMessage(`call in ${palletInfo.name}`, callName, callNames));
       }
-      const callData = await parseCallArgs(meta, palletInfo.name, callInfo.name, args);
+      const effectiveArgs = opts.parsedArgs !== undefined ? fileArgsToStrings(opts.parsedArgs) : args;
+      const callData = await parseCallArgs(meta, palletInfo.name, callInfo.name, effectiveArgs);
       if (opts.encode) {
         const { codec, location } = meta.builder.buildCall(palletInfo.name, callInfo.name);
         const encodedArgs = codec.enc(callData);
@@ -4437,8 +4461,8 @@ function normalizeValue2(lookup, entry, value) {
       return;
     }
     case "primitive": {
+      const prim = resolved.value;
       if (typeof value === "string") {
-        const prim = resolved.value;
         switch (prim) {
           case "bool":
             return value === "true";
@@ -4458,18 +4482,52 @@ function normalizeValue2(lookup, entry, value) {
             return parseInt(value, 10);
         }
       }
+      if (typeof value === "number") {
+        switch (prim) {
+          case "u64":
+          case "u128":
+          case "u256":
+          case "i64":
+          case "i128":
+          case "i256":
+            return BigInt(value);
+        }
+      }
       return value;
     }
     case "compact": {
       if (typeof value === "string") {
         return resolved.isBig ? BigInt(value) : parseInt(value, 10);
       }
+      if (typeof value === "number" && resolved.isBig) {
+        return BigInt(value);
+      }
       return value;
     }
     default:
       return value;
   }
 }
+function fileArgsToStrings(args) {
+  if (args == null)
+    return [];
+  if (typeof args === "object" && !Array.isArray(args)) {
+    return Object.values(args).map(serializeForCli);
+  }
+  if (Array.isArray(args)) {
+    return args.map(serializeForCli);
+  }
+  return [serializeForCli(args)];
+}
+function serializeForCli(v) {
+  if (typeof v === "string")
+    return v;
+  if (typeof v === "number" || typeof v === "bigint")
+    return String(v);
+  if (typeof v === "boolean" || v === null)
+    return String(v);
+  return JSON.stringify(v);
+}
 function parseEnumShorthand2(arg) {
   if (arg.startsWith("{") || arg.startsWith("[") || arg.startsWith("0x"))
     return null;
@@ -4763,6 +4821,130 @@ async function saveConfig2(config) {
 `);
 }
 
+// src/core/file-loader.ts
+init_errors();
+import { parse as parseYaml } from "yaml";
+var CATEGORIES = ["tx", "query", "const", "apis"];
+var FILE_EXTENSIONS = [".json", ".yaml", ".yml"];
+function isFilePath(dotpath) {
+  if (FILE_EXTENSIONS.some((ext) => dotpath.endsWith(ext)))
+    return true;
+  if (dotpath.startsWith("./") || dotpath.startsWith("/"))
+    return true;
+  return false;
+}
+function parseVarFlags(varFlags) {
+  if (!varFlags)
+    return {};
+  const flags = Array.isArray(varFlags) ? varFlags : [varFlags];
+  const vars = {};
+  for (const flag of flags) {
+    const eqIdx = flag.indexOf("=");
+    if (eqIdx === -1) {
+      throw new CliError(`Invalid --var format "${flag}". Expected KEY=VALUE.`);
+    }
+    const key = flag.slice(0, eqIdx);
+    const value = flag.slice(eqIdx + 1);
+    if (!key) {
+      throw new CliError(`Invalid --var format "${flag}". Key cannot be empty.`);
+    }
+    vars[key] = value;
+  }
+  return vars;
+}
+function substituteVars(text, vars) {
+  return text.replace(/\$\{([^}]+)\}/g, (_match, expr) => {
+    const defaultSep = expr.indexOf(":-");
+    let varName;
+    let defaultValue;
+    if (defaultSep !== -1) {
+      varName = expr.slice(0, defaultSep);
+      defaultValue = expr.slice(defaultSep + 2);
+    } else {
+      varName = expr;
+    }
+    if (varName in vars)
+      return vars[varName];
+    const envVal = process.env[varName];
+    if (envVal !== undefined)
+      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}.`);
+  });
+}
+async function loadCommandFile(filePath, cliVars) {
+  const file = Bun.file(filePath);
+  const exists = await file.exists();
+  if (!exists) {
+    throw new CliError(`File not found: ${filePath}`);
+  }
+  const rawText = await file.text();
+  if (!rawText.trim()) {
+    throw new CliError(`File is empty: ${filePath}`);
+  }
+  const isJson = filePath.endsWith(".json");
+  const fileVars = {};
+  try {
+    const preParsed = isJson ? JSON.parse(rawText) : parseYaml(rawText);
+    if (preParsed && typeof preParsed === "object" && !Array.isArray(preParsed) && preParsed.vars) {
+      const varsSection = preParsed.vars;
+      if (typeof varsSection === "object" && !Array.isArray(varsSection)) {
+        for (const [key, val] of Object.entries(varsSection)) {
+          fileVars[key] = String(val);
+        }
+      }
+    }
+  } catch {}
+  const mergedVars = { ...fileVars, ...cliVars };
+  const substituted = substituteVars(rawText, mergedVars);
+  let parsed;
+  try {
+    parsed = isJson ? JSON.parse(substituted) : parseYaml(substituted);
+  } catch (err) {
+    const format = isJson ? "JSON" : "YAML";
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new CliError(`Failed to parse ${format} file "${filePath}": ${msg}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`File "${filePath}" must contain a YAML/JSON object (not an array or scalar).`);
+  }
+  const doc = parsed;
+  const chain = doc.chain != null ? String(doc.chain) : undefined;
+  const foundCategories = CATEGORIES.filter((c) => (c in doc));
+  if (foundCategories.length === 0) {
+    throw new CliError(`File "${filePath}" must contain exactly one category key: ${CATEGORIES.join(", ")}. None found.`);
+  }
+  if (foundCategories.length > 1) {
+    throw new CliError(`File "${filePath}" contains multiple category keys: ${foundCategories.join(", ")}. Only one is allowed.`);
+  }
+  const category = foundCategories[0];
+  const categoryObj = doc[category];
+  if (!categoryObj || typeof categoryObj !== "object" || Array.isArray(categoryObj)) {
+    throw new CliError(`"${category}" in file "${filePath}" must be an object with a pallet name as key.`);
+  }
+  const palletEntries = Object.entries(categoryObj);
+  if (palletEntries.length !== 1) {
+    throw new CliError(`"${category}" in file "${filePath}" must contain exactly one pallet. Found: ${palletEntries.length === 0 ? "none" : palletEntries.map(([k]) => k).join(", ")}.`);
+  }
+  const [pallet, palletObj] = palletEntries[0];
+  if (!palletObj || typeof palletObj !== "object" || Array.isArray(palletObj)) {
+    throw new CliError(`"${category}.${pallet}" in file "${filePath}" must be an object with a call/item name as key.`);
+  }
+  const itemEntries = Object.entries(palletObj);
+  if (itemEntries.length !== 1) {
+    throw new CliError(`"${category}.${pallet}" in file "${filePath}" must contain exactly one item. Found: ${itemEntries.length === 0 ? "none" : itemEntries.map(([k]) => k).join(", ")}.`);
+  }
+  const [item, args] = itemEntries[0];
+  return {
+    chain,
+    category,
+    pallet,
+    item,
+    args: args ?? undefined
+  };
+}
+
 // src/core/update-notifier.ts
 init_store();
 import { readFileSync } from "node:fs";
@@ -4973,12 +5155,24 @@ if (process.argv[2] === "__complete") {
     process.exit(0);
   })();
 } else {
-  let printHelp = function() {
+  let collectVarFlags = function(argv) {
+    const vars = [];
+    for (let i = 0;i < argv.length; i++) {
+      if (argv[i] === "--var" && i + 1 < argv.length) {
+        vars.push(argv[i + 1]);
+        i++;
+      } else if (argv[i].startsWith("--var=")) {
+        vars.push(argv[i].slice(6));
+      }
+    }
+    return parseVarFlags(vars);
+  }, printHelp = function() {
     console.log(`dot/${version} \u2014 Polkadot CLI`);
     console.log();
     console.log("Usage:");
     console.log("  dot <category>[.Pallet[.Item]] [args] [options]");
     console.log("  dot [Chain.]<category>[.Pallet[.Item]] [args] [options]");
+    console.log("  dot <file.yaml|file.json> [options]");
     console.log();
     console.log("Categories:");
     console.log("  query     Query on-chain storage");
@@ -4996,6 +5190,7 @@ if (process.argv[2] === "__complete") {
     console.log("  dot events.Balances                     List events in Balances");
     console.log("  dot apis.Core.version                    Call a runtime API");
     console.log("  dot polkadot.query.System.Number        With chain prefix");
+    console.log("  dot ./transfer.yaml --from alice        Run from file");
     console.log();
     console.log("Commands:");
     console.log("  inspect [target]   Inspect chain metadata (alias: explore)");
@@ -5029,11 +5224,49 @@ if (process.argv[2] === "__complete") {
     default: "finalized"
   }).option("--limit <n>", "Max entries to return for map queries (0 = unlimited)", {
     default: 100
-  }).option("--dump", "Dump all entries of a storage map (without specifying a key)").action(async (dotpath, args, opts) => {
+  }).option("--dump", "Dump all entries of a storage map (without specifying a key)").option("--var <kv>", "Template variable for file input (KEY=VALUE, repeatable)").action(async (dotpath, args, opts) => {
     if (!dotpath) {
       printHelp();
       return;
     }
+    if (isFilePath(dotpath)) {
+      const cliVars = collectVarFlags(process.argv);
+      const cmd = await loadCommandFile(dotpath, cliVars);
+      const effectiveChain2 = opts.chain ?? cmd.chain;
+      const handlerOpts2 = { chain: effectiveChain2, rpc: opts.rpc, output: opts.output };
+      const target2 = `${cmd.pallet}.${cmd.item}`;
+      switch (cmd.category) {
+        case "tx":
+          await handleTx(target2, args, {
+            ...handlerOpts2,
+            from: opts.from,
+            dryRun: opts.dryRun,
+            encode: opts.encode,
+            ext: opts.ext,
+            wait: opts.wait,
+            parsedArgs: cmd.args
+          });
+          break;
+        case "query":
+          await handleQuery(target2, args, {
+            ...handlerOpts2,
+            limit: opts.limit,
+            dump: opts.dump,
+            parsedArgs: cmd.args
+          });
+          break;
+        case "const":
+          await handleConst(target2, handlerOpts2);
+          break;
+        case "apis":
+          await handleApis2(target2, args, {
+            ...handlerOpts2,
+            parsedArgs: cmd.args
+          });
+          break;
+      }
+      return;
+    }
     const config = await loadConfig2();
     const knownChains = Object.keys(config.chains);
     let parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {
@@ -45,7 +45,8 @@
     "@polkadot-labs/hdkd-helpers": "^0.0.27",
     "cac": "^6.7.14",
     "polkadot-api": "^1.23.3",
-    "ws": "^8.19.0"
+    "ws": "^8.19.0",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.5",