polkadot-cli 1.6.1 → 1.8.0

package/README.md

@@ -20,6 +20,8 @@ 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
+- ✅ Parachain sovereign accounts — derive child and sibling addresses from a parachain ID
 
 ### Preconfigured chains
 
@@ -495,6 +497,28 @@ dot tx Balances.transfer_keep_alive 5FHneW46... 1000000000000 --encode
 dot tx Sudo.sudo $(dot tx System.remark 0xcafe --encode) --from alice
 ```
 
+#### Decode call data to YAML / JSON
+
+Decode a hex-encoded call into a YAML or JSON file that is compatible with [file-based commands](#file-based-commands). This is useful for inspecting opaque call data, sharing human-readable transaction definitions, or editing parameters before re-submitting. Works offline from cached metadata and does not require `--from`.
+
+```bash
+# Decode a raw hex call to YAML
+dot tx.0x0001076465616462656566 --yaml
+
+# Decode a raw hex call to JSON
+dot tx.0x0001076465616462656566 --json
+
+# Encode a named call and output as YAML
+dot tx.System.remark 0xdeadbeef --yaml
+
+# Round-trip: encode to hex, decode to YAML, re-encode from file
+dot tx.System.remark 0xdeadbeef --encode           # 0x0001076465616462656566
+dot tx.0x0001076465616462656566 --yaml > remark.yaml
+dot ./remark.yaml --encode                          # same hex
+```
+
+`--yaml` / `--json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
+
 Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
 ```
@@ -572,6 +596,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`, `--yaml`, `--json`, `--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.
@@ -595,6 +798,32 @@ dot hash blake2b256 0xdeadbeef --output json
 
 Run `dot hash` with no arguments to see all available algorithms.
 
+### Parachain sovereign accounts
+
+Derive the sovereign account addresses for a parachain. These are deterministic accounts derived from a parachain ID — no chain connection required.
+
+- **Child** accounts represent a parachain on the relay chain (prefix `"para"`)
+- **Sibling** accounts represent a parachain on another parachain (prefix `"sibl"`)
+
+```bash
+# Show both child and sibling accounts
+dot parachain 1000
+
+# Show only the child (relay chain) account
+dot parachain 2004 --type child
+
+# Show only the sibling (parachain-to-parachain) account
+dot parachain 2004 --type sibling
+
+# Use Polkadot SS58 prefix (default: 42)
+dot parachain 1000 --prefix 0
+
+# JSON output
+dot parachain 1000 --output json
+```
+
+Run `dot parachain` with no arguments to see usage and examples.
+
 ### Getting help
 
 Every command supports `--help` to show its detailed usage, available actions, and examples:

package/dist/cli.mjs

@@ -966,6 +966,7 @@ function parseValue(arg) {
 // src/commands/tx.ts
 import { getViewBuilder } from "@polkadot-api/view-builder";
 import { Binary as Binary2 } from "polkadot-api";
+import { stringify as stringifyYaml } from "yaml";
 async function parseStructArgs(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
@@ -1080,8 +1081,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 +1102,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 +1345,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";
@@ -1950,6 +1968,12 @@ async function generateCompletions(currentWord, precedingWords) {
   if (firstArg === "hash") {
     return filterPrefix(getAlgorithmNames(), currentWord);
   }
+  if (firstArg === "parachain") {
+    if (prevWord === "--type") {
+      return filterPrefix(["child", "sibling"], currentWord);
+    }
+    return [];
+  }
   return completeDotpath(currentWord, config, knownChains, precedingWords);
 }
 function detectCategory(words, _knownChains) {
@@ -1973,7 +1997,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 +2048,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 +2116,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",
@@ -2113,7 +2137,7 @@ var init_complete = __esm(() => {
     apis: "apis",
     api: "apis"
   };
-  NAMED_COMMANDS = ["chain", "account", "inspect", "hash", "completions"];
+  NAMED_COMMANDS = ["chain", "account", "inspect", "hash", "parachain", "completions"];
   CHAIN_SUBCOMMANDS = ["add", "remove", "update", "list", "default"];
   ACCOUNT_SUBCOMMANDS = [
     "add",
@@ -2134,7 +2158,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.6.1";
+var version = "1.8.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -2621,7 +2645,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";
@@ -3745,6 +3772,97 @@ function registerInspectCommand(cli) {
   });
 }
 
+// src/commands/parachain.ts
+init_accounts();
+init_output();
+
+// src/core/parachain.ts
+var SOVEREIGN_ACCOUNT_TYPES = ["child", "sibling"];
+var PREFIXES = {
+  child: new Uint8Array([112, 97, 114, 97]),
+  sibling: new Uint8Array([115, 105, 98, 108])
+};
+function deriveSovereignAccount(paraId, type) {
+  const result = new Uint8Array(32);
+  result.set(PREFIXES[type], 0);
+  new DataView(result.buffer).setUint32(4, paraId, true);
+  return result;
+}
+function isValidParaId(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+
+// src/commands/parachain.ts
+init_errors();
+function printParachainHelp() {
+  console.log(`${BOLD}Usage:${RESET} dot parachain <paraId> [options]
+`);
+  console.log(`${BOLD}Description:${RESET}`);
+  console.log(`  Derive sovereign account addresses for a parachain.
+`);
+  console.log(`  ${DIM}Child accounts represent a parachain on the relay chain.${RESET}`);
+  console.log(`  ${DIM}Sibling accounts represent a parachain on another parachain.${RESET}
+`);
+  console.log(`${BOLD}Options:${RESET}`);
+  console.log(`  ${CYAN}--type <child|sibling>${RESET}  ${DIM}Account type (default: both)${RESET}`);
+  console.log(`  ${CYAN}--prefix <N>${RESET}             ${DIM}SS58 prefix (default: 42)${RESET}`);
+  console.log(`  ${CYAN}--output json${RESET}            ${DIM}Output as JSON${RESET}`);
+  console.log(`
+${BOLD}Examples:${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 1000${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 2004 --prefix 0${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 1000 --type sibling${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 2000 --output json${RESET}`);
+}
+function validateType(type) {
+  const lower = type.toLowerCase();
+  if (lower === "child" || lower === "sibling")
+    return lower;
+  throw new CliError(`Unknown account type "${type}". Valid types: child, sibling.`);
+}
+function registerParachainCommand(cli) {
+  cli.command("parachain [paraId]", "Derive parachain sovereign accounts").option("--type <type>", "Account type: child, sibling (default: both)").option("--prefix <number>", "SS58 prefix for address encoding (default: 42)").action(async (paraIdStr, opts) => {
+    if (!paraIdStr) {
+      printParachainHelp();
+      return;
+    }
+    const paraId = Number(paraIdStr);
+    if (!isValidParaId(paraId)) {
+      throw new CliError(`Invalid parachain ID "${paraIdStr}". Must be a non-negative integer (0 to 4294967295).`);
+    }
+    const prefix = opts.prefix != null ? Number(opts.prefix) : 42;
+    if (Number.isNaN(prefix) || prefix < 0) {
+      throw new CliError(`Invalid prefix "${opts.prefix}". Must be a non-negative integer.`);
+    }
+    const types = opts.type ? [validateType(opts.type)] : SOVEREIGN_ACCOUNT_TYPES;
+    const format = opts.output ?? "pretty";
+    if (format === "json") {
+      const result = { paraId, prefix };
+      for (const type of types) {
+        const accountId = deriveSovereignAccount(paraId, type);
+        result[type] = {
+          publicKey: publicKeyToHex(accountId),
+          ss58: toSs58(accountId, prefix)
+        };
+      }
+      console.log(formatJson(result));
+    } else {
+      printHeading(`Parachain ${paraId} — Sovereign Accounts`);
+      for (const type of types) {
+        const accountId = deriveSovereignAccount(paraId, type);
+        const hex = publicKeyToHex(accountId);
+        const ss58 = toSs58(accountId, prefix);
+        const label = type.charAt(0).toUpperCase() + type.slice(1);
+        console.log(`  ${BOLD}${label}:${RESET}`);
+        console.log(`    ${BOLD}Public Key:${RESET}  ${hex}`);
+        console.log(`    ${BOLD}SS58:${RESET}        ${ss58}`);
+        console.log(`    ${BOLD}Prefix:${RESET}      ${prefix}`);
+        console.log();
+      }
+    }
+  });
+}
+
 // src/commands/query.ts
 init_store();
 init_client();
@@ -3814,7 +3932,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) {
@@ -3895,6 +4016,7 @@ init_errors();
 init_focused_inspect();
 import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
 import { Binary as Binary3 } from "polkadot-api";
+import { stringify as stringifyYaml2 } from "yaml";
 function parseWaitLevel(raw) {
   switch (raw) {
     case "broadcast":
@@ -3945,7 +4067,7 @@ async function handleTx(target, args, opts) {
     console.log();
     return;
   }
-  if (!opts.from && !opts.encode) {
+  if (!opts.from && !opts.encode && !opts.yaml && !opts.json) {
     if (isRawCall) {
       throw new Error("--from is required (or use --encode to output hex without signing)");
     }
@@ -3958,6 +4080,15 @@ async function handleTx(target, args, opts) {
   if (opts.encode && isRawCall) {
     throw new Error("--encode cannot be used with raw call hex (already encoded)");
   }
+  if ((opts.yaml || opts.json) && opts.encode) {
+    throw new Error("--yaml/--json and --encode are mutually exclusive");
+  }
+  if ((opts.yaml || opts.json) && opts.dryRun) {
+    throw new Error("--yaml/--json and --dry-run are mutually exclusive");
+  }
+  if (opts.yaml && opts.json) {
+    throw new Error("--yaml and --json are mutually exclusive");
+  }
   const config = await loadConfig();
   const effectiveChain = opts.chain;
   let pallet;
@@ -3968,9 +4099,10 @@ async function handleTx(target, args, opts) {
     callName = target.slice(dotIdx + 1);
   }
   const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
-  const signer = opts.encode ? undefined : await resolveAccountSigner(opts.from);
+  const decodeOnly = opts.encode || opts.yaml || opts.json;
+  const signer = decodeOnly ? undefined : await resolveAccountSigner(opts.from);
   let clientHandle;
-  if (!opts.encode) {
+  if (!decodeOnly) {
     clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
   }
   try {
@@ -3987,7 +4119,7 @@ async function handleTx(target, args, opts) {
     }
     let unsafeApi;
     let txOptions;
-    if (!opts.encode) {
+    if (!decodeOnly) {
       const userExtOverrides = parseExtOption(opts.ext);
       const customSignedExtensions = buildCustomSignedExtensions(meta, userExtOverrides);
       txOptions = Object.keys(customSignedExtensions).length > 0 ? { customSignedExtensions } : undefined;
@@ -4000,9 +4132,14 @@ async function handleTx(target, args, opts) {
         throw new Error(`Extra arguments are not allowed when submitting a raw call hex.
 ` + "Usage: dot tx 0x<call_hex> --from <account>");
       }
+      callHex = target;
+      if (opts.yaml || opts.json) {
+        const fileObj = decodeCallToFileFormat(meta, callHex, chainName);
+        outputFileFormat(fileObj, !!opts.yaml);
+        return;
+      }
       const callBinary = Binary3.fromHex(target);
       tx = await unsafeApi.txFromCallData(callBinary);
-      callHex = target;
     } else {
       const palletNames = getPalletNames(meta);
       const palletInfo = findPallet(meta, pallet);
@@ -4014,12 +4151,19 @@ 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);
-      if (opts.encode) {
+      const effectiveArgs = opts.parsedArgs !== undefined ? fileArgsToStrings(opts.parsedArgs) : args;
+      const callData = await parseCallArgs(meta, palletInfo.name, callInfo.name, effectiveArgs);
+      if (opts.encode || opts.yaml || opts.json) {
         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(Binary3.fromBytes(fullCall).asHex());
+        const hex = Binary3.fromBytes(fullCall).asHex();
+        if (opts.encode) {
+          console.log(hex);
+          return;
+        }
+        const fileObj = decodeCallToFileFormat(meta, hex, chainName);
+        outputFileFormat(fileObj, !!opts.yaml);
         return;
       }
       tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
@@ -4140,6 +4284,58 @@ function decodeCallFallback(meta, callHex) {
   const argsStr = formatRawDecoded(args);
   return `${palletName2}.${callName} ${argsStr}`;
 }
+function decodeCallToFileFormat(meta, callHex, chainName) {
+  const callTypeId = meta.lookup.call;
+  if (callTypeId == null)
+    throw new Error("No RuntimeCall type ID in metadata");
+  const codec = meta.builder.buildDefinition(callTypeId);
+  const decoded = codec.dec(Binary3.fromHex(callHex).asBytes());
+  const palletName2 = decoded.type;
+  const call = decoded.value;
+  const callName = call.type;
+  const args = call.value;
+  return {
+    chain: chainName,
+    tx: {
+      [palletName2]: {
+        [callName]: sanitizeForSerialization(args) ?? null
+      }
+    }
+  };
+}
+function sanitizeForSerialization(value) {
+  if (value === undefined || value === null)
+    return null;
+  if (value instanceof Binary3)
+    return value.asHex();
+  if (typeof value === "bigint") {
+    if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER) {
+      return Number(value);
+    }
+    return value.toString();
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeForSerialization);
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = sanitizeForSerialization(v);
+    }
+    return result;
+  }
+  return String(value);
+}
+function outputFileFormat(obj, asYaml) {
+  if (asYaml) {
+    process.stdout.write(stringifyYaml2(obj));
+  } else {
+    console.log(JSON.stringify(obj, null, 2));
+  }
+}
 function formatRawDecoded(value) {
   if (value === undefined || value === null)
     return "null";
@@ -4437,8 +4633,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 +4654,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 +4993,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 +5327,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,12 +5362,16 @@ 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("  dot tx.0x1f0003... --yaml               Decode hex call to YAML");
+    console.log("  dot tx.System.remark 0xdead --json      Encode & output as JSON file format");
     console.log();
     console.log("Commands:");
     console.log("  inspect [target]   Inspect chain metadata (alias: explore)");
     console.log("  chain              Manage chain configurations");
     console.log("  account            Manage accounts");
     console.log("  hash               Hash utilities");
+    console.log("  parachain          Derive parachain sovereign accounts");
     console.log("  completions <sh>   Generate shell completions (zsh, bash, fish)");
     console.log();
     console.log("Global options:");
@@ -5024,16 +5394,57 @@ if (process.argv[2] === "__complete") {
   registerInspectCommand(cli);
   registerAccountCommands(cli);
   registerHashCommand(cli);
+  registerParachainCommand(cli);
   registerCompletionsCommand(cli);
-  cli.command("[dotpath] [...args]").option("--from <name>", "Account to sign with (for tx)").option("--dry-run", "Estimate fees without submitting (for tx)").option("--encode", "Encode call to hex without signing (for tx)").option("--ext <json>", "Custom signed extension values as JSON (for tx)").option("-w, --wait <level>", "Resolve at: broadcast, best-block (or best), finalized (for tx)", {
+  cli.command("[dotpath] [...args]").option("--from <name>", "Account to sign with (for tx)").option("--dry-run", "Estimate fees without submitting (for tx)").option("--encode", "Encode call to hex without signing (for tx)").option("--yaml", "Decode call to YAML file format (for tx)").option("--json", "Decode call to JSON file format (for tx)").option("--ext <json>", "Custom signed extension values as JSON (for tx)").option("-w, --wait <level>", "Resolve at: broadcast, best-block (or best), finalized (for tx)", {
     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,
+            yaml: opts.yaml,
+            json: opts.json,
+            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;
@@ -5069,6 +5480,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
+            yaml: opts.yaml,
+            json: opts.json,
             ext: opts.ext,
             wait: opts.wait
           });
@@ -5078,6 +5491,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
+            yaml: opts.yaml,
+            json: opts.json,
             ext: opts.ext,
             wait: opts.wait
           });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.6.1",
+  "version": "1.8.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",