polkadot-cli 1.21.0 → 1.23.0

package/README.md

@@ -81,6 +81,24 @@ To pull the latest skill updates:
 /plugin marketplace update polkadot-cli
 ```
 
+## Plugins
+
+`dot` supports git/cargo-style external subcommands: any executable named `dot-<name>` on your PATH runs as `dot <name>`, with the remaining arguments forwarded verbatim, stdio inherited, and the plugin's exit code passed through.
+
+```bash
+npm install -g dot-example     # ships a `dot-example` binary
+dot example status --json      # runs: dot-example status --json
+```
+
+This is how domain-specific tooling extends `dot` without the CLI loading third-party code into its own process. Plugins are ordinary child processes — the intended pattern is that a plugin invokes `dot` itself for anything chain- or signing-related (e.g. `dot tx.… --from <account>`), so key handling stays inside `dot`.
+
+Plugins receive a `DOT_BIN` environment variable pointing at the entry script of the `dot` that dispatched them (the same convention as cargo's `CARGO`), so they can invoke the exact same installation rather than whatever `dot` is first on PATH.
+
+Notes:
+
+- Only a bare first token dispatches: `dot foo.bar` is always dot-path syntax, `./file.yaml` is always file input — neither will hit the plugin lookup.
+- Built-in commands and categories always win over a plugin of the same name.
+
 ## Usage
 
 ### Manage chains
@@ -97,7 +115,8 @@ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
 
 # Add a parachain under a relay (auto-detects parachain ID)
-dot chain add local-asset-hub --rpc ws://localhost:9945 --relay local-relay
+# Name parachains `{relay}-{parachain}` — see "Naming convention" below
+dot chain add local-relay-asset-hub --rpc ws://localhost:9945 --relay local-relay
 
 # Add a parachain with explicit parachain ID
 dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
@@ -119,6 +138,24 @@ dot chain update --all      # updates all configured chains in parallel
 dot chain remove kusama
 ```
 
+#### Naming convention
+
+Name chains `{relay}-{parachain}`: the parent relay's name, a hyphen, then the parachain's role. Every preconfigured chain already follows this pattern (`polkadot-asset-hub`, `polkadot-bridge-hub`, `paseo-people`, …), and reusing it for chains you add keeps the relay/parachain topology readable.
+
+| Chain kind | Recommended name | Examples |
+|------------|------------------|----------|
+| Relay chain | `{relay}` | `polkadot`, `kusama`, `paseo` |
+| Parachain | `{relay}-{parachain}` | `polkadot-asset-hub`, `kusama-bridge-hub`, `paseo-people` |
+
+The relay prefix is what keeps chains distinct: parachain IDs collide across relays (Asset Hub is `1000` on both Polkadot and Paseo), so the name — not the ID — is how you select a chain (`dot polkadot-asset-hub.query…`). A relay-prefixed name also mirrors the `dot chain list` tree, which groups parachains under their relay.
+
+```bash
+# Recommended — relay-prefixed name
+dot chain add kusama-asset-hub --rpc wss://asset-hub-kusama-rpc.polkadot.io --relay kusama --parachain-id 1000
+```
+
+Use lowercase, hyphen-separated names (chain names resolve case-insensitively).
+
 #### Chain topology
 
 `dot chain list` displays chains as a tree, grouping parachains under their parent relay:
@@ -297,9 +334,10 @@ dot account derive treasury treasury-staking --path //staking
 # Use it — the env var is read at signing time
 MY_SECRET="word1 word2 ..." dot polkadot.tx.System.remark 0xdead --from ci-signer
 
-# Remove one or more accounts
+# Remove one or more accounts (delete and rm are aliases for remove)
 dot account remove my-validator
 dot account delete my-validator stale-key
+dot account rm my-validator stale-key
 
 # Export accounts (secrets redacted by default)
 dot account export
@@ -777,6 +815,8 @@ dot polkadot.const.Balances.ExistentialDeposit --json | jq
 
 Works offline from cached metadata after the first fetch. The chain is required. Prefer the chain-prefix-on-target form (`dot inspect polkadot.System`); `--chain` is equivalent. Note that `dot polkadot.inspect.X` does **not** parse — `inspect` is a top-level command, not a dotpath category.
 
+`inspect` is **forgiving**: it accepts the same dot-paths you use to invoke a call and degrades to discovery rather than erroring. A `kind` segment (`tx`/`query`/`const`/`events`/`errors`/…) is tolerated and ignored — so `dot inspect polkadot.tx.System.remark` describes the `System.remark` call just like `dot inspect polkadot.System.remark` does. Partial paths list rather than fail: `dot inspect polkadot.query.System` (and the bare `dot inspect System`) list the pallet's items.
+
 Output is **width-aware**: short type signatures stay on a single line, longer ones expand across multiple lines with field names aligned. Composite struct fields, enum variants, and call arguments are color-coded (cyan field names, yellow primitives, magenta container keywords like `Vec`/`Option`, green enum variants) when stdout is a TTY; piped output stays plain.
 
 ```bash
@@ -1200,6 +1240,13 @@ dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice --dr
 # Submit (omit --dry-run)
 dot polkadot.tx.System.remark 0xdeadbeef --from alice
 
+# Force every tx to dry-run via the global DOT_DRY_RUN env var — a safety net
+# for scripts and demos. A hint is printed to stderr; the command behaves
+# exactly as if --dry-run had been passed.
+DOT_DRY_RUN=1 dot polkadot.tx.System.remark 0xdeadbeef --from alice
+# stderr: ⚠ DOT_DRY_RUN is set — extrinsics will be simulated, not submitted.
+# stdout: (the dry-run output above — no broadcast)
+
 # Submit a raw SCALE-encoded call (e.g. from a multisig proposal or another tool)
 dot polkadot.tx 0x000010deadbeef --from alice --dry-run
 
@@ -2192,6 +2239,24 @@ cd - && rm -rf "$tmp"        # nothing ever touched ~/.polkadot
 
 For secrets that should never hit disk at all, combine workspaces with `--env` secret sources (see [Manage accounts](#manage-accounts)).
 
+### `DOT_DRY_RUN` — force every extrinsic to dry-run
+
+Set `DOT_DRY_RUN` to a truthy value (`1`, `true`, `yes`, or `on`, case-insensitive) to make **every** extrinsic-submitting command behave as if `--dry-run` had been passed: the transaction is simulated (call decoded, fees estimated) and **never broadcast**. This is a global safety net for scripts, demos, and CI dry-runs where you want to be sure nothing lands on-chain.
+
+When active, the CLI prints a one-line hint to **stderr** (so it never corrupts `--json` or piped stdout):
+
+```bash
+DOT_DRY_RUN=1 dot polkadot.tx.Balances.transfer_keep_alive bob 1000000000000 --from alice
+# stderr: ⚠ DOT_DRY_RUN is set — extrinsics will be simulated, not submitted.
+# stdout: the usual dry-run report (Chain / From / Call / Decode / Estimated fees)
+
+# Set it for a whole shell session as a safety net:
+export DOT_DRY_RUN=1
+dot polkadot.tx.System.remark 0xdeadbeef --from alice   # simulated, not submitted
+```
+
+**Precedence:** an explicit per-command flag always wins. `--dry-run` forces a dry-run; `--no-dry-run` forces a real submission even when `DOT_DRY_RUN` is set. The env var only supplies the default when no flag is given. Decode-only paths (`--encode`, `--to-yaml`, `--to-json`) never submit anything, so `DOT_DRY_RUN` leaves them untouched.
+
 ### `DOT_TRUST_CACHED_METADATA` — skip the staleness check
 
 Set `DOT_TRUST_CACHED_METADATA=1` to disable the post-failure stale-metadata check on `dot tx`, `dot tx --dry-run`, and `dot query`. When set, errors propagate exactly as the runtime / RPC reported them, with no extra `state_getRuntimeVersion` / `state_getStorageHash` round-trip. Useful in CI loops where you've just refreshed metadata manually and don't want the overhead.

package/dist/cli.mjs

@@ -917,6 +917,31 @@ var init_output = __esm(() => {
   SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 });
 
+// src/platform/cli.ts
+function withHelp(command, printHelp) {
+  command[HELP_PRINTER] = printHelp ?? (() => command.outputHelp());
+  return command;
+}
+function readRawOptionValue(name, argv = process.argv) {
+  const flag = `--${name}`;
+  const prefix = `${flag}=`;
+  let value;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--")
+      break;
+    if (arg === flag && i + 1 < argv.length)
+      value = argv[i + 1];
+    else if (arg.startsWith(prefix))
+      value = arg.slice(prefix.length);
+  }
+  return value;
+}
+var HELP_PRINTER;
+var init_cli = __esm(() => {
+  HELP_PRINTER = Symbol.for("polkadot-cli.helpPrinter");
+});
+
 // src/features/verifiable/lib.ts
 var exports_lib = {};
 __export(exports_lib, {
@@ -3490,23 +3515,6 @@ var init_input = __esm(() => {
   init_hash();
 });
 
-// src/platform/cli.ts
-function readRawOptionValue(name, argv = process.argv) {
-  const flag = `--${name}`;
-  const prefix = `${flag}=`;
-  let value;
-  for (let i = 0;i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--")
-      break;
-    if (arg === flag && i + 1 < argv.length)
-      value = argv[i + 1];
-    else if (arg.startsWith(prefix))
-      value = arg.slice(prefix.length);
-  }
-  return value;
-}
-
 // src/platform/index.ts
 var init_platform = __esm(() => {
   init_accounts_store();
@@ -3515,6 +3523,7 @@ var init_platform = __esm(() => {
   init_input();
   init_output();
   init_errors();
+  init_cli();
 });
 
 // src/features/verifiable/commands.ts
@@ -3810,8 +3819,8 @@ var exports_complete = {};
 __export(exports_complete, {
   generateCompletions: () => generateCompletions
 });
-function matchCategory2(s) {
-  return CATEGORY_ALIASES2[s.toLowerCase()];
+function matchCategory3(s) {
+  return CATEGORY_ALIASES3[s.toLowerCase()];
 }
 async function loadPallets(_config, chainName) {
   const raw = await loadMetadata(chainName);
@@ -3942,7 +3951,7 @@ function detectCategory(words, _knownChains) {
       continue;
     const parts = w.split(".");
     for (const part of parts) {
-      const cat = matchCategory2(part);
+      const cat = matchCategory3(part);
       if (cat)
         return cat;
     }
@@ -3964,11 +3973,11 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
     return filterPrefix(candidates, partial);
   }
   const first = completeSegments[0] ?? "";
-  const firstIsCategory = matchCategory2(first) !== undefined;
+  const firstIsCategory = matchCategory3(first) !== undefined;
   const firstIsChain = knownChains.some((c) => c.toLowerCase() === first.toLowerCase());
   const chainFromFlag = resolveChainFromArgs(precedingWords, config);
   if (firstIsCategory) {
-    const category = matchCategory2(first);
+    const category = matchCategory3(first);
     if (category === "apis") {
       return completeApisCategory(first, numComplete, endsWithDot, completeSegments, currentWord, config, chainFromFlag);
     }
@@ -4028,7 +4037,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       return filterPrefix(candidates, currentWord);
     }
     if (numComplete === 2) {
-      const category = matchCategory2(completeSegments[1]);
+      const category = matchCategory3(completeSegments[1]);
       if (!category)
         return [];
       if (category === "apis") {
@@ -4049,7 +4058,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       return filterPrefix(candidates, endsWithDot ? currentWord.slice(0, -1) : currentWord);
     }
     if (numComplete === 3) {
-      const category = matchCategory2(completeSegments[1]);
+      const category = matchCategory3(completeSegments[1]);
       if (!category)
         return [];
       if (category === "apis") {
@@ -4131,7 +4140,7 @@ async function completeRpcCategory(prefix, numComplete, endsWithDot, currentWord
   }
   return [];
 }
-var CATEGORIES2, CATEGORY_ALIASES2, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
+var CATEGORIES2, CATEGORY_ALIASES3, NAMED_COMMANDS, CHAIN_SUBCOMMANDS, ACCOUNT_SUBCOMMANDS, GLOBAL_OPTIONS, TX_OPTIONS, QUERY_OPTIONS;
 var init_complete = __esm(() => {
   init_accounts_store();
   init_store();
@@ -4149,7 +4158,7 @@ var init_complete = __esm(() => {
     "extensions",
     "rpc"
   ];
-  CATEGORY_ALIASES2 = {
+  CATEGORY_ALIASES3 = {
     query: "query",
     tx: "tx",
     const: "const",
@@ -4207,7 +4216,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.21.0";
+var version = "1.23.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -4341,6 +4350,7 @@ function isValidParaId(value) {
 }
 
 // src/commands/account.ts
+init_cli();
 var ACCOUNT_HELP = `
 ${BOLD}Usage:${RESET}
   $ dot account add <name> <ss58|hex>                                Add a watch-only address (no secret)
@@ -4357,7 +4367,7 @@ ${BOLD}Usage:${RESET}
   $ dot account inspect --pallet-id <id> [--prefix <N>]              Derive a pallet sovereign (no save — script-friendly)
   $ dot account inspect --parachain <id> --parachain-type <t>        Derive a parachain sovereign (no save — script-friendly)
   $ dot account list                                                 List all accounts
-  $ dot account remove|delete <name> [name2] ...                     Remove stored account(s)
+  $ dot account remove|delete|rm <name> [name2] ...                  Remove stored account(s)
 
 ${BOLD}Examples:${RESET}
   $ dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
@@ -4395,7 +4405,7 @@ ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       Raw private keys cannot be HD-derived, so --path is rejected for them.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [...names]", "Manage local accounts (create, import, list, remove, export)").alias("accounts").option("--secret <value>", "Secret for import: BIP39 mnemonic, 0x 32-byte hex seed, or 0x 64-byte raw private key").option("--env <varName>", "Environment variable name holding the secret").option("--path <derivation>", "Derivation path (e.g. //staking, //polkadot//0/wallet)").option("--parachain <id>", "Derive a parachain sovereign account (requires --parachain-type)").option("--parachain-type <type>", "Parachain sovereign type: child or sibling").option("--pallet-id <id>", "Derive a pallet sovereign account from an 8-byte PalletId").option("--prefix <number>", "SS58 prefix for address encoding (default: 42)").option("--file <path>", "Input/output file for batch import/export").option("--overwrite", "Overwrite existing accounts on batch import").option("--dry-run", "Preview batch import without applying changes").option("--include-secrets", "Include secrets in export (redacted by default)").option("--watch-only", "Export only watch-only accounts").option("--show-secret", "Reveal the 64-byte sr25519 expanded private key (inspect only)").action(async (action, names, opts) => {
+  const command = cli.command("account [action] [...names]", "Manage local accounts (create, import, list, remove, export)").alias("accounts").option("--secret <value>", "Secret for import: BIP39 mnemonic, 0x 32-byte hex seed, or 0x 64-byte raw private key").option("--env <varName>", "Environment variable name holding the secret").option("--path <derivation>", "Derivation path (e.g. //staking, //polkadot//0/wallet)").option("--parachain <id>", "Derive a parachain sovereign account (requires --parachain-type)").option("--parachain-type <type>", "Parachain sovereign type: child or sibling").option("--pallet-id <id>", "Derive a pallet sovereign account from an 8-byte PalletId").option("--prefix <number>", "SS58 prefix for address encoding (default: 42)").option("--file <path>", "Input/output file for batch import/export").option("--overwrite", "Overwrite existing accounts on batch import").option("--dry-run", "Preview batch import without applying changes").option("--include-secrets", "Include secrets in export (redacted by default)").option("--watch-only", "Export only watch-only accounts").option("--show-secret", "Reveal the 64-byte sr25519 expanded private key (inspect only)").action(async (action, names, opts) => {
     if (!action) {
       if (process.argv[2] === "accounts")
         return accountList(opts);
@@ -4428,6 +4438,7 @@ function registerAccountCommands(cli) {
         return accountList(opts);
       case "delete":
       case "remove":
+      case "rm":
         return accountRemove(names, opts);
       case "inspect":
         return accountInspect(names[0], opts);
@@ -4435,6 +4446,7 @@ function registerAccountCommands(cli) {
         return accountInspect(action, opts);
     }
   });
+  withHelp(command, () => console.log(ACCOUNT_HELP));
 }
 async function accountCreate(name, opts) {
   if (!name) {
@@ -5528,6 +5540,7 @@ async function fetchRpcMethods(rpcUrl) {
 
 // src/commands/chain.ts
 init_rpc_registry();
+init_cli();
 var CHAIN_HELP = `
 ${BOLD}Usage:${RESET}
   $ dot chain add <name> --rpc <url>    Add a chain via WebSocket RPC
@@ -5561,7 +5574,7 @@ ${BOLD}Examples:${RESET}
   $ dot chain import my-chains.json --no-metadata
 `.trimStart();
 function registerChainCommands(cli) {
-  cli.command("chain [action] [...names]", "Manage chains (add, remove, update, list, export, import)").alias("chains").option("--all", "Update/export all configured chains").option("--relay <name>", "Parent relay chain for this parachain").option("--parachain-id <id>", "Parachain ID (auto-detected if omitted with --relay)").option("--file <path>", "Output/input file for export/import").option("--overwrite", "Overwrite existing chains on import").option("--dry-run", "Preview import without applying changes").option("--no-metadata", "Skip automatic metadata fetch after import").option("-v, --verbose", "Show RPC endpoints in `chains` list output").action(async (action, names, opts) => {
+  const command = cli.command("chain [action] [...names]", "Manage chains (add, remove, update, list, export, import)").alias("chains").option("--all", "Update/export all configured chains").option("--relay <name>", "Parent relay chain for this parachain").option("--parachain-id <id>", "Parachain ID (auto-detected if omitted with --relay)").option("--file <path>", "Output/input file for export/import").option("--overwrite", "Overwrite existing chains on import").option("--dry-run", "Preview import without applying changes").option("--no-metadata", "Skip automatic metadata fetch after import").option("-v, --verbose", "Show RPC endpoints in `chains` list output").action(async (action, names, opts) => {
     if (!action) {
       if (process.argv[2] === "chains")
         return chainList(opts);
@@ -5595,6 +5608,7 @@ function registerChainCommands(cli) {
       }
     }
   });
+  withHelp(command, () => console.log(CHAIN_HELP));
 }
 async function refreshRpcMethods(chainName, rpcUrl, silent = false) {
   try {
@@ -6036,6 +6050,7 @@ async function chainImport(filePath, opts) {
 }
 
 // src/commands/completions.ts
+init_cli();
 var ZSH_SCRIPT = `_dot_completions() {
   emulate -L zsh
   local -a completions
@@ -6104,7 +6119,7 @@ var SCRIPTS = {
   fish: FISH_SCRIPT
 };
 function registerCompletionsCommand(cli) {
-  cli.command("completions <shell>", "Generate shell completion script (zsh, bash, fish)").action((shell) => {
+  const command = cli.command("completions <shell>", "Generate shell completion script (zsh, bash, fish)").action((shell) => {
     const script = SCRIPTS[shell];
     if (!script) {
       console.error(`Unsupported shell "${shell}". Supported: ${Object.keys(SCRIPTS).join(", ")}`);
@@ -6117,6 +6132,7 @@ function registerCompletionsCommand(cli) {
     }
     console.log(script);
   });
+  withHelp(command);
 }
 
 // src/commands/const.ts
@@ -6894,6 +6910,7 @@ async function handleExtensions(target, opts) {
 init_hash();
 init_input();
 init_output();
+init_cli();
 init_errors();
 function printAlgorithmHelp() {
   console.log(`${BOLD}Usage:${RESET} dot hash <algorithm> <data> [options]
@@ -6915,7 +6932,7 @@ ${BOLD}Examples:${RESET}`);
   console.log(`  ${DIM}$ echo -n "hello" | dot hash sha256 --stdin${RESET}`);
 }
 function registerHashCommand(cli) {
-  cli.command("hash [algorithm] [data]", "Compute cryptographic hashes").option("--file <path>", "Hash file contents (raw bytes)").option("--stdin", "Read data from stdin").action(async (algorithm, data, opts) => {
+  const command = cli.command("hash [algorithm] [data]", "Compute cryptographic hashes").option("--file <path>", "Hash file contents (raw bytes)").option("--stdin", "Read data from stdin").action(async (algorithm, data, opts) => {
     if (!algorithm) {
       printAlgorithmHelp();
       return;
@@ -6936,6 +6953,7 @@ function registerHashCommand(cli) {
       console.log(hexHash);
     }
   });
+  withHelp(command, printAlgorithmHelp);
 }
 
 // src/commands/inspect.ts
@@ -6944,11 +6962,44 @@ init_client();
 init_metadata();
 init_output();
 init_pretty_type();
+init_cli();
+
+// src/utils/parse-dot-path.ts
+var CATEGORY_ALIASES = {
+  query: "query",
+  tx: "tx",
+  const: "const",
+  consts: "const",
+  constants: "const",
+  events: "events",
+  event: "events",
+  errors: "errors",
+  error: "errors",
+  apis: "apis",
+  api: "apis",
+  extensions: "extensions",
+  extension: "extensions",
+  ext: "extensions",
+  rpc: "rpc"
+};
+function matchCategory(segment) {
+  return CATEGORY_ALIASES[segment.toLowerCase()];
+}
 
 // src/utils/parse-target.ts
+function stripKindSegment(parts, knownChains) {
+  if (parts.length >= 3 && parts[0] && knownChains.some((c) => c.toLowerCase() === parts[0].toLowerCase()) && parts[1] && matchCategory(parts[1])) {
+    return [parts[0], ...parts.slice(2)];
+  }
+  if (parts.length >= 2 && parts[0] && matchCategory(parts[0])) {
+    return parts.slice(1);
+  }
+  return parts;
+}
 function parseTarget(input, options) {
-  const parts = input.split(".");
+  let parts = input.split(".");
   if (options?.allowPalletOnly) {
+    parts = stripKindSegment(parts, options.knownChains ?? []);
     switch (parts.length) {
       case 1:
         if (!parts[0]) {
@@ -6969,7 +7020,7 @@ function parseTarget(input, options) {
         }
         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`);
+        throw new Error(`Invalid target "${input}". Expected format: Pallet, Pallet.Item, Chain.Pallet.Item, ` + `or a dot-path with a kind segment (e.g. polkadot.tx.System.remark)`);
     }
   }
   switch (parts.length) {
@@ -6996,7 +7047,7 @@ function resolveTargetChain(target, chainFlag) {
 
 // src/commands/inspect.ts
 function registerInspectCommand(cli) {
-  cli.command("inspect [target]", "Inspect chain metadata (pallets, storage, constants, calls, events, errors)").alias("explore").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+  const command = cli.command("inspect [target]", "Inspect chain metadata (pallets, storage, constants, calls, events, errors)").alias("explore").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
     const config = await loadConfig();
     const knownChains = Object.keys(config.chains);
     let effectiveChain = opts.chain;
@@ -7364,6 +7415,7 @@ function registerInspectCommand(cli) {
     ];
     throw new Error(suggestMessage(`item in ${pallet.name}`, itemName, allItems));
   });
+  withHelp(command);
 }
 
 // src/commands/metadata.ts
@@ -7371,6 +7423,7 @@ init_store();
 init_client();
 init_metadata();
 init_output();
+init_cli();
 init_errors();
 function buildMetadataPayload(chainName, meta, fingerprint) {
   return {
@@ -7413,12 +7466,14 @@ async function handleMetadata(chain, opts) {
 `);
 }
 function registerMetadataCommand(cli) {
-  cli.command("metadata <chain>", "Fetch chain metadata (decoded JSON; --raw for SCALE hex)").option("--raw", "Print SCALE-encoded metadata bytes as hex instead of decoded JSON").option("--cached", "Use cached metadata instead of fetching fresh from the chain").option("--rpc <url>", "Override RPC endpoint(s)").action((chain, opts) => handleMetadata(chain, opts));
+  const command = cli.command("metadata <chain>", "Fetch chain metadata (decoded JSON; --raw for SCALE hex)").option("--raw", "Print SCALE-encoded metadata bytes as hex instead of decoded JSON").option("--cached", "Use cached metadata instead of fetching fresh from the chain").option("--rpc <url>", "Override RPC endpoint(s)").action((chain, opts) => handleMetadata(chain, opts));
+  withHelp(command);
 }
 
 // src/commands/parachain.ts
 init_accounts();
 init_output();
+init_cli();
 init_errors();
 function printParachainHelp() {
   console.log(`${BOLD}Usage:${RESET} dot parachain <paraId> [options]
@@ -7447,7 +7502,7 @@ function validateType(type) {
   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) => {
+  const command = 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) => {
     console.error("Warning: `dot parachain` is deprecated; use `dot account inspect --parachain <id> --parachain-type <child|sibling>` instead. Will be removed in a future release.");
     if (!paraIdStr) {
       printParachainHelp();
@@ -7487,6 +7542,7 @@ function registerParachainCommand(cli) {
       }
     }
   });
+  withHelp(command, printParachainHelp);
 }
 
 // src/commands/query.ts
@@ -7831,6 +7887,7 @@ init_accounts();
 init_hash();
 init_input();
 init_output();
+init_cli();
 init_errors();
 var SUPPORTED_TYPES = ["sr25519"];
 function isSupportedType(type) {
@@ -7863,7 +7920,7 @@ ${BOLD}Examples:${RESET}`);
   console.log(`  ${DIM}$ dot sign "hello" --from alice --output json${RESET}`);
 }
 function registerSignCommand(cli) {
-  cli.command("sign [message]", "Sign a message with an account keypair").option("--from <name>", "Account to sign with").option("--type <algo>", "Signature type (default: sr25519)").option("--file <path>", "Sign file contents (raw bytes)").option("--stdin", "Read data from stdin").action(async (message, opts) => {
+  const command = cli.command("sign [message]", "Sign a message with an account keypair").option("--from <name>", "Account to sign with").option("--type <algo>", "Signature type (default: sr25519)").option("--file <path>", "Sign file contents (raw bytes)").option("--stdin", "Read data from stdin").action(async (message, opts) => {
     if (!message && !opts.file && !opts.stdin) {
       printSignHelp();
       return;
@@ -7897,6 +7954,7 @@ function registerSignCommand(cli) {
       console.log(`  ${BOLD}Enum:${RESET}       ${result.enum}`);
     }
   });
+  withHelp(command, printSignHelp);
 }
 
 // src/commands/tx.ts
@@ -9354,6 +9412,7 @@ function watchTransactionJson(observable, level, options) {
 init_store();
 init_workspace();
 init_output();
+init_cli();
 init_errors();
 import { mkdir as mkdir3, stat } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
@@ -9407,8 +9466,10 @@ Source: ${SOURCE_LABELS[resolved.source]}
 `);
 }
 function registerWorkspaceCommands(cli) {
-  cli.command("init", "Initialize a local .polkadot workspace in the current directory").action(() => handleInit());
-  cli.command("which", "Show the active config root (workspace, DOT_HOME, or global)").action((opts) => handleWhich(opts));
+  const initCommand = cli.command("init", "Initialize a local .polkadot workspace in the current directory").action(() => handleInit());
+  withHelp(initCommand);
+  const whichCommand = cli.command("which", "Show the active config root (workspace, DOT_HOME, or global)").action((opts) => handleWhich(opts));
+  withHelp(whichCommand);
 }
 
 // src/config/store.ts
@@ -9469,6 +9530,48 @@ async function saveConfig2(config) {
 `);
 }
 
+// src/core/dry-run.ts
+init_output();
+function isGlobalDryRun() {
+  const raw = process.env.DOT_DRY_RUN?.trim().toLowerCase();
+  if (raw === undefined || raw === "")
+    return false;
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+function resolveDryRun(explicitFlag, decodeOnly = false) {
+  if (explicitFlag !== undefined)
+    return explicitFlag;
+  if (decodeOnly)
+    return false;
+  return isGlobalDryRun();
+}
+var hintPrinted = false;
+function printGlobalDryRunHint() {
+  if (hintPrinted)
+    return;
+  hintPrinted = true;
+  process.stderr.write(`${YELLOW}${BOLD}⚠ DOT_DRY_RUN is set${RESET}${YELLOW} — extrinsics will be simulated, not submitted.${RESET}
+`);
+}
+
+// src/core/external-command.ts
+var PLUGIN_PREFIX = "dot-";
+function isExternalCommandCandidate(name) {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name);
+}
+function findExternalCommand(name) {
+  if (!isExternalCommandCandidate(name))
+    return null;
+  return Bun.which(`${PLUGIN_PREFIX}${name}`, { PATH: process.env.PATH ?? "" });
+}
+function runExternalCommand(binPath, args) {
+  const result = Bun.spawnSync([binPath, ...args], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: { ...process.env, DOT_BIN: process.argv[1] ?? "dot" }
+  });
+  return result.exitCode ?? 1;
+}
+
 // src/core/file-loader.ts
 init_errors();
 import { access as access4, readFile as readFile7 } from "node:fs/promises";
@@ -9796,7 +9899,7 @@ var RAW_STRING_FLAGS = [
   ["member", "member"]
 ];
 function registerVerifiableCommands(cli) {
-  cli.command("verifiable [action] [...rest]", "Bandersnatch member keys, ring-VRF proofs, signing and verification").option("--entropy-key <key>", "Entropy-derivation key (omit = lite, 'candidate' = full)").option("--context <value>", "32-byte ring/proof context (alias/prove/verify)").option("--message <data>", "Message to sign/bind/verify (text or 0x hex)").option("--file <path>", "Read message from a file (raw bytes)").option("--stdin", "Read message from stdin").option("--members <hex|file>", "SCALE-encoded Vec<[u8;32]> ring (prove/verify)").option("--root <hex>", "768-byte ring root/commitment (verify)").option("--proof <hex>", "Ring-VRF proof bytes (verify)").option("--signature <hex>", "Bandersnatch signature (verify-sig)").option("--member <hex>", "32-byte member public key (verify-sig)").option("--ring-exponent <n>", "Ring exponent: 9 (default), 10, or 14").action(async (action, rest, opts) => {
+  const command = cli.command("verifiable [action] [...rest]", "Bandersnatch member keys, ring-VRF proofs, signing and verification").option("--entropy-key <key>", "Entropy-derivation key (omit = lite, 'candidate' = full)").option("--context <value>", "32-byte ring/proof context (alias/prove/verify)").option("--message <data>", "Message to sign/bind/verify (text or 0x hex)").option("--file <path>", "Read message from a file (raw bytes)").option("--stdin", "Read message from stdin").option("--members <hex|file>", "SCALE-encoded Vec<[u8;32]> ring (prove/verify)").option("--root <hex>", "768-byte ring root/commitment (verify)").option("--proof <hex>", "Ring-VRF proof bytes (verify)").option("--signature <hex>", "Bandersnatch signature (verify-sig)").option("--member <hex>", "32-byte member public key (verify-sig)").option("--ring-exponent <n>", "Ring exponent: 9 (default), 10, or 14").action(async (action, rest, opts) => {
     if (!action) {
       console.log(VERIFIABLE_HELP);
       return;
@@ -9809,9 +9912,19 @@ function registerVerifiableCommands(cli) {
     const { runVerifiable: runVerifiable2 } = await Promise.resolve().then(() => (init_commands(), exports_commands));
     return runVerifiable2(action, rest, opts);
   });
+  withHelp(command, () => console.log(VERIFIABLE_HELP));
 }
 
 // src/platform/cli.ts
+var HELP_PRINTER2 = Symbol.for("polkadot-cli.helpPrinter");
+function printMatchedCommandHelp(cli) {
+  const matched = cli.matchedCommand;
+  const printer = matched?.[HELP_PRINTER2];
+  if (!printer)
+    return false;
+  printer();
+  return true;
+}
 function registerGlobalOptions(cli) {
   cli.option("--chain <name>", "Target chain (required)");
   cli.option("--rpc <url>", "Override RPC endpoint for this call");
@@ -9873,7 +9986,7 @@ function formatRuntimeError2(err) {
 }
 
 // src/utils/parse-dot-path.ts
-var CATEGORY_ALIASES = {
+var CATEGORY_ALIASES2 = {
   query: "query",
   tx: "tx",
   const: "const",
@@ -9890,8 +10003,8 @@ var CATEGORY_ALIASES = {
   ext: "extensions",
   rpc: "rpc"
 };
-function matchCategory(segment) {
-  return CATEGORY_ALIASES[segment.toLowerCase()];
+function matchCategory2(segment) {
+  return CATEGORY_ALIASES2[segment.toLowerCase()];
 }
 function matchChain(segment, knownChains) {
   return knownChains.some((c) => c.toLowerCase() === segment.toLowerCase());
@@ -9900,35 +10013,35 @@ function parseDotPath(input, knownChains = []) {
   const parts = input.split(".");
   switch (parts.length) {
     case 1: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat)
         return { category: cat };
       throw new Error(`Unknown command "${parts[0]}". Expected a category (query, tx, const, events, errors, apis, extensions, rpc) or a named command.`);
     }
     case 2: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat) {
         return { category: cat, pallet: parts[1] };
       }
-      const cat2 = matchCategory(parts[1]);
+      const cat2 = matchCategory2(parts[1]);
       if (cat2 && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat2 };
       }
       throw new Error(`Unknown command "${input}". Expected format: category.Pallet or Chain.category (e.g. query.System or polkadot.query)`);
     }
     case 3: {
-      const cat = matchCategory(parts[0]);
+      const cat = matchCategory2(parts[0]);
       if (cat) {
         return { category: cat, pallet: parts[1], item: parts[2] };
       }
-      const cat2 = matchCategory(parts[1]);
+      const cat2 = matchCategory2(parts[1]);
       if (cat2 && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat2, pallet: parts[2] };
       }
       throw new Error(`Unknown command "${input}". Expected format: category.Pallet.Item or Chain.category.Pallet`);
     }
     case 4: {
-      const cat = matchCategory(parts[1]);
+      const cat = matchCategory2(parts[1]);
       if (cat && matchChain(parts[0], knownChains)) {
         return { chain: parts[0], category: cat, pallet: parts[2], item: parts[3] };
       }
@@ -10019,6 +10132,9 @@ if (process.argv[2] === "__complete") {
     console.log("  init               Initialize a local .polkadot workspace in this directory");
     console.log("  which              Show the active config root (workspace, DOT_HOME, or global)");
     console.log();
+    console.log("Plugins:");
+    console.log('  dot <name> \u2026       Runs a "dot-<name>" executable found on PATH (git/cargo-style)');
+    console.log();
     console.log("Global options:");
     console.log("  --chain <name>     Target chain (required)");
     console.log("  --rpc <url>        Override RPC endpoint");
@@ -10060,12 +10176,17 @@ if (process.argv[2] === "__complete") {
       };
       const target2 = `${cmd.pallet}.${cmd.item}`;
       switch (cmd.category) {
-        case "tx":
+        case "tx": {
+          const fileDecodeOnly = Boolean(opts.encode || opts.toYaml || opts.toJson);
+          const fileDryRun = resolveDryRun(opts.dryRun, fileDecodeOnly);
+          if (fileDryRun && isGlobalDryRun() && opts.dryRun === undefined) {
+            printGlobalDryRunHint();
+          }
           await handleTx(target2, args, {
             ...handlerOpts2,
             from: opts.from,
             unsigned: opts.unsigned ?? cmd.unsigned,
-            dryRun: opts.dryRun,
+            dryRun: fileDryRun,
             encode: opts.encode,
             toYaml: opts.toYaml,
             toJson: opts.toJson,
@@ -10079,6 +10200,7 @@ if (process.argv[2] === "__complete") {
             parsedArgs: cmd.args
           });
           break;
+        }
         case "query":
           await handleQuery(target2, args, {
             ...handlerOpts2,
@@ -10106,7 +10228,14 @@ if (process.argv[2] === "__complete") {
     try {
       parsed = parseDotPath(dotpath, knownChains);
     } catch {
-      throw new CliError2(`Unknown command "${dotpath}". Run "dot --help" for available commands.`);
+      if (process.argv[2] === dotpath) {
+        const externalBin = findExternalCommand(dotpath);
+        if (externalBin) {
+          process.exit(runExternalCommand(externalBin, process.argv.slice(3)));
+        }
+      }
+      const pluginHint = isExternalCommandCandidate(dotpath) ? ` No "dot-${dotpath}" plugin found on PATH.` : "";
+      throw new CliError2(`Unknown command "${dotpath}". Run "dot --help" for available commands.${pluginHint}`);
     }
     const isFlatCategory = parsed.category === "rpc" || parsed.category === "extensions";
     if (!parsed.pallet && args.length > 0) {
@@ -10135,11 +10264,16 @@ if (process.argv[2] === "__complete") {
         await handleQuery(target, args, { ...handlerOpts, dump: opts.dump, at: atRaw });
         break;
       case "tx": {
+        const decodeOnly = Boolean(opts.encode || opts.toYaml || opts.toJson);
+        const dryRun = resolveDryRun(opts.dryRun, decodeOnly);
+        if (dryRun && isGlobalDryRun() && opts.dryRun === undefined) {
+          printGlobalDryRunHint();
+        }
         const txOpts = {
           ...handlerOpts,
           from: opts.from,
           unsigned: opts.unsigned,
-          dryRun: opts.dryRun,
+          dryRun,
           encode: opts.encode,
           toYaml: opts.toYaml,
           toJson: opts.toJson,
@@ -10224,7 +10358,9 @@ if (process.argv[2] === "__complete") {
       if (cli.options.version) {
         await showUpdateAndExit(0);
       } else if (cli.options.help) {
-        if (cli.matchedCommand) {
+        if (printMatchedCommandHelp(cli)) {
+          await showUpdateAndExit(0);
+        } else if (cli.matchedCommand) {
           const result = cli.runMatchedCommand();
           if (result && typeof result.then === "function") {
             await result.then(() => showUpdateAndExit(0), handleError);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {
@@ -21,8 +21,7 @@
     "test:coverage": "bun test --concurrent --coverage --coverage-reporter=lcov --coverage-dir=coverage",
     "prepare": "husky",
     "changeset": "changeset",
-    "version": "changeset version",
-    "release": "changeset publish"
+    "version": "changeset version"
   },
   "license": "MIT",
   "keywords": [
@@ -34,7 +33,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/peetzweg/polkadot-cli.git"
+    "url": "git+https://github.com/paritytech/polkadot-cli.git"
   },
   "dependencies": {
     "@noble/hashes": "^2.0.1",
@@ -45,9 +44,9 @@
     "@polkadot-labs/hdkd": "^0.0.28",
     "@polkadot-labs/hdkd-helpers": "^0.0.29",
     "@scure/sr25519": "^1.0.0",
-    "cac": "^6.7.14",
-    "polkadot-api": "^2.1.4",
-    "verifiablejs": "1.3.0",
+    "cac": "^7.0.0",
+    "polkadot-api": "^2.1.7",
+    "verifiablejs": "1.4.0",
     "yaml": "^2.8.3"
   },
   "devDependencies": {