polkadot-cli 0.10.0 → 0.12.0

package/README.md

@@ -4,7 +4,26 @@
 
 A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from your terminal.
 
-Ships with Polkadot as the default chain. Add any Substrate-based chain by pointing to its RPC endpoint.
+Ships with Polkadot and all system parachains preconfigured with multiple fallback RPC endpoints. Add any Substrate-based chain by pointing to its RPC endpoint(s).
+
+### Preconfigured chains
+
+| Network | Chain | Light client |
+|---------|-------|:---:|
+| Polkadot | `polkadot` (relay, default) | yes |
+| | `polkadot-asset-hub` | yes |
+| | `polkadot-bridge-hub` | yes |
+| | `polkadot-collectives` | yes |
+| | `polkadot-coretime` | yes |
+| | `polkadot-people` | yes |
+| Paseo (testnet) | `paseo` (relay) | yes |
+| | `paseo-asset-hub` | yes |
+| | `paseo-bridge-hub` | — |
+| | `paseo-collectives` | — |
+| | `paseo-coretime` | yes |
+| | `paseo-people` | yes |
+
+Each chain ships with multiple RPC endpoints from decentralized infrastructure providers (IBP, Dotters, Dwellir, and others). The CLI automatically falls back to the next endpoint if the primary is unreachable.
 
 ## Install
 
@@ -19,13 +38,21 @@ This installs the `dot` command globally.
 ### Manage chains
 
 ```bash
-# Add a chain
+# Show chain help
+dot chain               # shows available actions
+dot chains              # shorthand, same as above
+
+# Add a chain (single RPC)
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+
+# Add a chain with fallback RPCs (repeat --rpc for each endpoint)
+dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
+
+# Add a chain via light client
 dot chain add westend --light-client
 
 # List configured chains
-dot chains              # shorthand
-dot chain list          # equivalent
+dot chain list
 
 # Re-fetch metadata after a runtime upgrade
 dot chain update          # updates default chain
@@ -45,24 +72,37 @@ Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for t
 > **Security warning:** Account secrets (mnemonics and seeds) are currently stored **unencrypted** in `~/.polkadot/accounts.json`. Do not use this for high-value accounts on mainnet. Encrypted storage is planned for a future release. Use `--env` to keep secrets off disk entirely.
 
 ```bash
+# Show account help
+dot account             # shows available actions
+dot accounts            # shorthand, same as above
+
 # List all accounts (dev + stored)
-dot accounts            # shorthand
-dot account list        # equivalent
+dot account list
 
 # Create a new account (generates a mnemonic)
 dot account create my-validator
 
+# Create with a derivation path
+dot account create my-staking --path //staking
+
 # Import from a BIP39 mnemonic
 dot account import treasury --secret "word1 word2 ... word12"
 
-# Add an env-var-backed account (secret stays off disk)
-dot account add ci-signer --env MY_SECRET
+# Import with a derivation path
+dot account import hot-wallet --secret "word1 word2 ... word12" --path //hot
+
+# Import an env-var-backed account (secret stays off disk)
+dot account import ci-signer --env MY_SECRET
+
+# Derive a child account from an existing one
+dot account derive treasury treasury-staking --path //staking
 
 # Use it — the env var is read at signing time
 MY_SECRET="word1 word2 ..." dot tx System.remark 0xdead --from ci-signer
 
-# Remove an account
+# Remove one or more accounts
 dot account remove my-validator
+dot account delete my-validator stale-key
 ```
 
 #### Env-var-backed accounts
@@ -70,11 +110,40 @@ dot account remove my-validator
 For CI/CD and security-conscious workflows, store a reference to an environment variable instead of the secret itself:
 
 ```bash
-dot account add ci-signer --env MY_SECRET
+dot account import ci-signer --env MY_SECRET
 ```
 
+`--secret` and `--env` are mutually exclusive. `add` is an alias for `import`.
+
 The secret is never written to disk. At signing time, the CLI reads `$MY_SECRET` and derives the keypair. If the variable is not set, the CLI errors with a clear message. `account list` shows an `(env: MY_SECRET)` badge and resolves the address live when the variable is available.
 
+#### Derivation paths
+
+Use `--path` with `create`, `import`, or the `derive` action to derive child keys from the same secret. Different paths produce different keypairs, enabling key separation (e.g. staking vs. governance) without managing multiple mnemonics.
+
+```bash
+# Create with a derivation path
+dot account create my-staking --path //staking
+
+# Multi-segment path (hard + soft junctions)
+dot account create multi --path //polkadot//0/wallet
+
+# Import with a path
+dot account import hot --secret "word1 word2 ..." --path //hot
+
+# Derive a child from an existing account
+dot account derive treasury treasury-staking --path //staking
+```
+
+`derive` copies the source account's secret and applies the given path. It requires both a source name, a new name, and `--path`. Works with env-backed accounts too — the derived account shares the same env var reference.
+
+`account list` shows the derivation path next to the account name:
+
+```
+  treasury-staking (//staking)  5FHneW46...
+  ci-signer (//ci) (env: MY_SECRET)  5EPCUjPx...
+```
+
 **Supported secret formats for import:**
 
 | Format | Example | Status |
@@ -96,6 +165,8 @@ dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
+Chain names are case-insensitive — `Polkadot.System.Account`, `POLKADOT.System.Account`, and `polkadot.System.Account` all resolve the same way. The same applies to `--chain Polkadot` and `dot chain default Polkadot`.
+
 The `--chain` flag and default chain still work as before. If both a chain prefix and `--chain` flag are provided, the CLI errors.
 
 ### Query storage
@@ -276,12 +347,24 @@ dot hash blake2b256 0xdeadbeef --output json
 
 Run `dot hash` with no arguments to see all available algorithms.
 
+### Getting help
+
+Every command supports `--help` to show its detailed usage, available actions, and examples:
+
+```bash
+dot --help              # global help with all commands
+dot account --help      # same as `dot account` — shows account actions
+dot chain --help        # same as `dot chain` — shows chain actions
+dot hash --help         # same as `dot hash` — shows algorithms and examples
+```
+
 ### Global options
 
 | Flag | Description |
 |------|-------------|
+| `--help` | Show help (global or command-specific) |
 | `--chain <name>` | Target chain (default from config) |
-| `--rpc <url>` | Override RPC endpoint for this call |
+| `--rpc <url>` | Override RPC endpoint(s) for this call (repeat for fallback) |
 | `--light-client` | Use Smoldot light client |
 | `--output json` | Raw JSON output (default: pretty) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
@@ -314,13 +397,15 @@ After each command, the CLI checks whether a newer version is available on npm a
 ╰───────────────────────────────────────────────╯
 ```
 
-The version check runs in the background on startup and caches the result for 24 hours in `~/.polkadot/update-check.json`. It never blocks the CLI.
+The version check runs in the background on startup and caches the result for 24 hours in `~/.polkadot/update-check.json`. Before exiting, the CLI waits up to 500ms for the check to finish so the cache file is written — even for fast commands like `--help` and `--version`. Long-running commands (queries, transactions) are unaffected since the check completes well before they finish.
+
+If the network is unreachable, the failed check is cached for 1 hour so subsequent runs don't incur the 500ms wait repeatedly.
 
 The notification is automatically suppressed when:
 
 - `DOT_NO_UPDATE_CHECK=1` is set
 - `CI` environment variable is set (any value)
-- stdout is not a TTY (e.g. piped output)
+- stderr is not a TTY (e.g. piped output)
 
 ## Configuration
 

package/dist/cli.mjs

@@ -5,7 +5,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "0.10.0";
+var version = "0.12.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -17,14 +17,120 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 // src/config/types.ts
+function primaryRpc(rpc) {
+  return Array.isArray(rpc) ? rpc[0] : rpc;
+}
 var DEFAULT_CONFIG = {
   defaultChain: "polkadot",
   chains: {
     polkadot: {
-      rpc: "wss://rpc.polkadot.io"
+      rpc: [
+        "wss://polkadot.ibp.network",
+        "wss://polkadot.dotters.network",
+        "wss://polkadot-rpc.n.dwellir.com",
+        "wss://polkadot-rpc.publicnode.com",
+        "wss://rpc-polkadot.luckyfriday.io",
+        "wss://polkadot.api.onfinality.io/public-ws",
+        "wss://rpc-polkadot.helixstreet.io",
+        "wss://polkadot-rpc-tn.dwellir.com",
+        "wss://polkadot.public.curie.radiumblock.co/ws",
+        "wss://rpc-polkadot.stakeworld.io",
+        "wss://polkadot.rpc.subquery.network/public/ws",
+        "wss://rpc.polkadot.io"
+      ]
+    },
+    "polkadot-asset-hub": {
+      rpc: [
+        "wss://polkadot-asset-hub-rpc.polkadot.io",
+        "wss://asset-hub-polkadot.ibp.network",
+        "wss://asset-hub-polkadot.dotters.network",
+        "wss://asset-hub-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-asset-hub-polkadot.luckyfriday.io",
+        "wss://statemint.api.onfinality.io/public-ws",
+        "wss://statemint-rpc-tn.dwellir.com",
+        "wss://statemint.public.curie.radiumblock.co/ws",
+        "wss://asset-hub-polkadot.rpc.permanence.io"
+      ]
+    },
+    "polkadot-bridge-hub": {
+      rpc: [
+        "wss://polkadot-bridge-hub-rpc.polkadot.io",
+        "wss://bridge-hub-polkadot.ibp.network",
+        "wss://bridge-hub-polkadot.dotters.network",
+        "wss://bridge-hub-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-bridge-hub-polkadot.luckyfriday.io",
+        "wss://bridgehub-polkadot.api.onfinality.io/public-ws",
+        "wss://polkadot-bridge-hub-rpc-tn.dwellir.com",
+        "wss://bridgehub-polkadot.public.curie.radiumblock.co/ws"
+      ]
+    },
+    "polkadot-collectives": {
+      rpc: [
+        "wss://polkadot-collectives-rpc.polkadot.io",
+        "wss://collectives-polkadot.ibp.network",
+        "wss://collectives-polkadot.dotters.network",
+        "wss://collectives-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-collectives-polkadot.luckyfriday.io",
+        "wss://collectives.api.onfinality.io/public-ws",
+        "wss://polkadot-collectives-rpc-tn.dwellir.com",
+        "wss://collectives.public.curie.radiumblock.co/ws"
+      ]
+    },
+    "polkadot-coretime": {
+      rpc: [
+        "wss://polkadot-coretime-rpc.polkadot.io",
+        "wss://coretime-polkadot.ibp.network",
+        "wss://coretime-polkadot.dotters.network",
+        "wss://coretime-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-coretime-polkadot.luckyfriday.io",
+        "wss://coretime-polkadot.api.onfinality.io/public-ws"
+      ]
+    },
+    "polkadot-people": {
+      rpc: [
+        "wss://polkadot-people-rpc.polkadot.io",
+        "wss://people-polkadot.ibp.network",
+        "wss://people-polkadot.dotters.network",
+        "wss://people-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-people-polkadot.luckyfriday.io",
+        "wss://people-polkadot.api.onfinality.io/public-ws"
+      ]
+    },
+    paseo: {
+      rpc: [
+        "wss://paseo.ibp.network",
+        "wss://paseo.dotters.network",
+        "wss://paseo-rpc.n.dwellir.com",
+        "wss://paseo.rpc.amforc.com"
+      ]
+    },
+    "paseo-asset-hub": {
+      rpc: [
+        "wss://asset-hub-paseo.ibp.network",
+        "wss://asset-hub-paseo.dotters.network",
+        "wss://asset-hub-paseo-rpc.n.dwellir.com",
+        "wss://sys.turboflakes.io/asset-hub-paseo"
+      ]
+    },
+    "paseo-bridge-hub": {
+      rpc: ["wss://bridge-hub-paseo.ibp.network", "wss://bridge-hub-paseo.dotters.network"]
+    },
+    "paseo-collectives": {
+      rpc: ["wss://collectives-paseo.ibp.network", "wss://collectives-paseo.dotters.network"]
+    },
+    "paseo-coretime": {
+      rpc: ["wss://coretime-paseo.ibp.network", "wss://coretime-paseo.dotters.network"]
+    },
+    "paseo-people": {
+      rpc: [
+        "wss://people-paseo.ibp.network",
+        "wss://people-paseo.dotters.network",
+        "wss://people-paseo.rpc.amforc.com"
+      ]
     }
   }
 };
+var BUILTIN_CHAIN_NAMES = new Set(Object.keys(DEFAULT_CONFIG.chains));
 
 // src/config/store.ts
 var DOT_DIR = join(homedir(), ".polkadot");
@@ -53,8 +159,11 @@ async function fileExists(path) {
 async function loadConfig() {
   await ensureDir(DOT_DIR);
   if (await fileExists(CONFIG_PATH)) {
-    const data = await readFile(CONFIG_PATH, "utf-8");
-    return JSON.parse(data);
+    const saved = JSON.parse(await readFile(CONFIG_PATH, "utf-8"));
+    return {
+      ...saved,
+      chains: { ...DEFAULT_CONFIG.chains, ...saved.chains }
+    };
   }
   await saveConfig(DEFAULT_CONFIG);
   return DEFAULT_CONFIG;
@@ -80,14 +189,19 @@ async function removeChainData(chainName) {
   const dir = getChainDir(chainName);
   await rm(dir, { recursive: true, force: true });
 }
+function findChainName(config, input) {
+  if (config.chains[input])
+    return input;
+  return Object.keys(config.chains).find((k) => k.toLowerCase() === input.toLowerCase());
+}
 function resolveChain(config, chainFlag) {
-  const name = chainFlag ?? config.defaultChain;
-  const chain = config.chains[name];
-  if (!chain) {
+  const input = chainFlag ?? config.defaultChain;
+  const name = findChainName(config, input);
+  if (!name) {
     const available = Object.keys(config.chains).join(", ");
-    throw new Error(`Unknown chain "${name}". Available chains: ${available}`);
+    throw new Error(`Unknown chain "${input}". Available chains: ${available}`);
   }
-  return { name, chain };
+  return { name, chain: config.chains[name] };
 }
 
 // src/config/accounts-store.ts
@@ -166,24 +280,24 @@ function getDevAddress(name, prefix = 42) {
   const keypair = getDevKeypair(name);
   return ss58Address(keypair.publicKey, prefix);
 }
-function createNewAccount() {
+function createNewAccount(path = "") {
   const mnemonic = generateMnemonic();
   const entropy = mnemonicToEntropy(mnemonic);
   const miniSecret = entropyToMiniSecret(entropy);
   const derive = sr25519CreateDerive(miniSecret);
-  const keypair = derive("");
+  const keypair = derive(path);
   return { mnemonic, publicKey: keypair.publicKey };
 }
-function importAccount(secret) {
+function importAccount(secret, path = "") {
   const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(secret);
   if (isHexSeed) {
-    const keypair2 = deriveFromHexSeed(secret, "");
+    const keypair2 = deriveFromHexSeed(secret, path);
     return { publicKey: keypair2.publicKey };
   }
   if (!validateMnemonic(secret)) {
     throw new Error("Invalid secret. Expected a 0x-prefixed 32-byte hex seed or a valid BIP39 mnemonic.");
   }
-  const keypair = deriveFromMnemonic(secret, "");
+  const keypair = deriveFromMnemonic(secret, path);
   return { publicKey: keypair.publicKey };
 }
 function publicKeyToHex(publicKey) {
@@ -210,12 +324,12 @@ function resolveSecret(secret) {
   }
   return secret;
 }
-function tryDerivePublicKey(envVarName) {
+function tryDerivePublicKey(envVarName, path = "") {
   const value = process.env[envVarName];
   if (!value)
     return null;
   try {
-    const { publicKey } = importAccount(value);
+    const { publicKey } = importAccount(value, path);
     return publicKeyToHex(publicKey);
   } catch {
     return null;
@@ -334,39 +448,49 @@ class Spinner {
 // src/commands/account.ts
 var ACCOUNT_HELP = `
 ${BOLD}Usage:${RESET}
-  $ dot account create <name>                Create a new account
-  $ dot account import <name> --secret <s>   Import from BIP39 mnemonic
-  $ dot account add <name> --env <VAR>       Add account backed by env variable
-  $ dot account list                         List all accounts
-  $ dot account remove <name>                Remove a stored account
+  $ dot account create|new <name> [--path <derivation>]              Create a new account
+  $ dot account import|add <name> --secret <s> [--path <derivation>] Import from BIP39 mnemonic
+  $ dot account import|add <name> --env <VAR> [--path <derivation>]  Import account backed by env variable
+  $ dot account derive <source> <new-name> --path <derivation>       Derive a child account
+  $ dot account list                                                 List all accounts
+  $ dot account remove|delete <name> [name2] ...                     Remove stored account(s)
 
 ${BOLD}Examples:${RESET}
   $ dot account create my-validator
+  $ dot account create my-staking --path //staking
+  $ dot account create multi --path //polkadot//0/wallet
   $ dot account import treasury --secret "word1 word2 ... word12"
-  $ dot account add ci-signer --env MY_SECRET
+  $ dot account import ci-signer --env MY_SECRET --path //ci
+  $ dot account derive treasury treasury-staking --path //staking
   $ dot account list
-  $ dot account remove my-validator
+  $ dot account remove my-validator stale-key
 
 ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       Use --env to keep secrets off disk entirely.
       Hex seed import (0x...) is not supported via CLI.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [name]", "Manage local accounts (create, import, add, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").option("--env <varName>", "Environment variable name holding the secret").action(async (action, name, opts) => {
+  cli.command("account [action] [...names]", "Manage local accounts (create, import, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").option("--env <varName>", "Environment variable name holding the secret").option("--path <derivation>", "Derivation path (e.g. //staking, //polkadot//0/wallet)").action(async (action, names, opts) => {
     if (!action) {
-      return accountList();
+      if (process.argv[2] === "accounts")
+        return accountList();
+      console.log(ACCOUNT_HELP);
+      return;
     }
     switch (action) {
+      case "new":
       case "create":
-        return accountCreate(name);
+        return accountCreate(names[0], opts);
       case "import":
-        return accountImport(name, opts);
       case "add":
-        return accountAdd(name, opts);
+        return accountImport(names[0], opts);
+      case "derive":
+        return accountDerive(names[0], names[1], opts);
       case "list":
         return accountList();
+      case "delete":
       case "remove":
-        return accountRemove(name);
+        return accountRemove(names);
       default:
         console.error(`Unknown action "${action}".
 `);
@@ -375,7 +499,7 @@ function registerAccountCommands(cli) {
     }
   });
 }
-async function accountCreate(name) {
+async function accountCreate(name, opts) {
   if (!name) {
     console.error(`Account name is required.
 `);
@@ -389,18 +513,21 @@ async function accountCreate(name) {
   if (findAccount(accountsFile, name)) {
     throw new Error(`Account "${name}" already exists.`);
   }
-  const { mnemonic, publicKey } = createNewAccount();
+  const path = opts.path ?? "";
+  const { mnemonic, publicKey } = createNewAccount(path);
   const hexPub = publicKeyToHex(publicKey);
   const address = toSs58(publicKey);
   accountsFile.accounts.push({
     name,
     secret: mnemonic,
     publicKey: hexPub,
-    derivationPath: ""
+    derivationPath: path
   });
   await saveAccounts(accountsFile);
   printHeading("Account Created");
   console.log(`  ${BOLD}Name:${RESET}     ${name}`);
+  if (path)
+    console.log(`  ${BOLD}Path:${RESET}     ${path}`);
   console.log(`  ${BOLD}Address:${RESET}  ${address}`);
   console.log(`  ${BOLD}Mnemonic:${RESET} ${mnemonic}`);
   console.log();
@@ -414,10 +541,16 @@ async function accountImport(name, opts) {
     console.error('Usage: dot account import <name> --secret "mnemonic or hex seed"');
     process.exit(1);
   }
-  if (!opts.secret) {
-    console.error(`--secret is required.
+  if (opts.secret && opts.env) {
+    console.error(`Use --secret or --env, not both.
+`);
+    process.exit(1);
+  }
+  if (!opts.secret && !opts.env) {
+    console.error(`--secret or --env is required.
 `);
     console.error('Usage: dot account import <name> --secret "mnemonic or hex seed"');
+    console.error("       dot account import <name> --env <VAR>");
     process.exit(1);
   }
   if (isDevAccount(name)) {
@@ -427,58 +560,115 @@ async function accountImport(name, opts) {
   if (findAccount(accountsFile, name)) {
     throw new Error(`Account "${name}" already exists.`);
   }
-  const { publicKey } = importAccount(opts.secret);
-  const hexPub = publicKeyToHex(publicKey);
-  const address = toSs58(publicKey);
-  accountsFile.accounts.push({
-    name,
-    secret: opts.secret,
-    publicKey: hexPub,
-    derivationPath: ""
-  });
-  await saveAccounts(accountsFile);
-  printHeading("Account Imported");
-  console.log(`  ${BOLD}Name:${RESET}    ${name}`);
-  console.log(`  ${BOLD}Address:${RESET} ${address}`);
-  console.log();
-}
-async function accountAdd(name, opts) {
-  if (!name) {
-    console.error(`Account name is required.
+  const path = opts.path ?? "";
+  if (opts.env) {
+    const publicKey = tryDerivePublicKey(opts.env, path) ?? "";
+    accountsFile.accounts.push({
+      name,
+      secret: { env: opts.env },
+      publicKey,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Imported");
+    console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+    if (path)
+      console.log(`  ${BOLD}Path:${RESET}    ${path}`);
+    console.log(`  ${BOLD}Env:${RESET}     ${opts.env}`);
+    if (publicKey) {
+      console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
+    } else {
+      console.log(`  ${YELLOW}Address will resolve when $${opts.env} is set.${RESET}`);
+    }
+    console.log();
+  } else {
+    const { publicKey } = importAccount(opts.secret, path);
+    const hexPub = publicKeyToHex(publicKey);
+    const address = toSs58(publicKey);
+    accountsFile.accounts.push({
+      name,
+      secret: opts.secret,
+      publicKey: hexPub,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Imported");
+    console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+    if (path)
+      console.log(`  ${BOLD}Path:${RESET}    ${path}`);
+    console.log(`  ${BOLD}Address:${RESET} ${address}`);
+    console.log();
+  }
+}
+async function accountDerive(sourceName, newName, opts) {
+  if (!sourceName) {
+    console.error(`Source account name is required.
 `);
-    console.error("Usage: dot account add <name> --env <VAR>");
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
     process.exit(1);
   }
-  if (!opts.env) {
-    console.error(`--env is required.
+  if (!newName) {
+    console.error(`New account name is required.
 `);
-    console.error("Usage: dot account add <name> --env <VAR>");
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
     process.exit(1);
   }
-  if (isDevAccount(name)) {
-    throw new Error(`"${name}" is a built-in dev account and cannot be used as a custom account name.`);
+  if (!opts.path) {
+    console.error(`--path is required for derive.
+`);
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
+    process.exit(1);
   }
-  const accountsFile = await loadAccounts();
-  if (findAccount(accountsFile, name)) {
-    throw new Error(`Account "${name}" already exists.`);
+  if (isDevAccount(newName)) {
+    throw new Error(`"${newName}" is a built-in dev account and cannot be used as a custom account name.`);
   }
-  const publicKey = tryDerivePublicKey(opts.env) ?? "";
-  accountsFile.accounts.push({
-    name,
-    secret: { env: opts.env },
-    publicKey,
-    derivationPath: ""
-  });
-  await saveAccounts(accountsFile);
-  printHeading("Account Added");
-  console.log(`  ${BOLD}Name:${RESET}  ${name}`);
-  console.log(`  ${BOLD}Env:${RESET}   ${opts.env}`);
-  if (publicKey) {
-    console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
+  const accountsFile = await loadAccounts();
+  const source = findAccount(accountsFile, sourceName);
+  if (!source) {
+    throw new Error(`Source account "${sourceName}" not found.`);
+  }
+  if (findAccount(accountsFile, newName)) {
+    throw new Error(`Account "${newName}" already exists.`);
+  }
+  const path = opts.path;
+  if (isEnvSecret(source.secret)) {
+    const publicKey = tryDerivePublicKey(source.secret.env, path) ?? "";
+    accountsFile.accounts.push({
+      name: newName,
+      secret: source.secret,
+      publicKey,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Derived");
+    console.log(`  ${BOLD}Name:${RESET}    ${newName}`);
+    console.log(`  ${BOLD}Source:${RESET}  ${sourceName}`);
+    console.log(`  ${BOLD}Path:${RESET}    ${path}`);
+    console.log(`  ${BOLD}Env:${RESET}     ${source.secret.env}`);
+    if (publicKey) {
+      console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
+    } else {
+      console.log(`  ${YELLOW}Address will resolve when $${source.secret.env} is set.${RESET}`);
+    }
+    console.log();
   } else {
-    console.log(`  ${YELLOW}Address will resolve when $${opts.env} is set.${RESET}`);
+    const { publicKey } = importAccount(source.secret, path);
+    const hexPub = publicKeyToHex(publicKey);
+    const address = toSs58(publicKey);
+    accountsFile.accounts.push({
+      name: newName,
+      secret: source.secret,
+      publicKey: hexPub,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Derived");
+    console.log(`  ${BOLD}Name:${RESET}    ${newName}`);
+    console.log(`  ${BOLD}Source:${RESET}  ${sourceName}`);
+    console.log(`  ${BOLD}Path:${RESET}    ${path}`);
+    console.log(`  ${BOLD}Address:${RESET} ${address}`);
+    console.log();
   }
-  console.log();
 }
 async function accountList() {
   printHeading("Dev Accounts");
@@ -492,12 +682,15 @@ async function accountList() {
     printHeading("Stored Accounts");
     for (const account of accountsFile.accounts) {
       let displayName = account.name;
+      if (account.derivationPath) {
+        displayName += ` (${account.derivationPath})`;
+      }
       let address;
       if (isEnvSecret(account.secret)) {
         displayName += ` (env: ${account.secret.env})`;
         let pubKey = account.publicKey;
         if (!pubKey) {
-          pubKey = tryDerivePublicKey(account.secret.env) ?? "";
+          pubKey = tryDerivePublicKey(account.secret.env, account.derivationPath) ?? "";
         }
         address = pubKey ? toSs58(pubKey) : "n/a";
       } else {
@@ -511,24 +704,44 @@ async function accountList() {
   }
   console.log();
 }
-async function accountRemove(name) {
-  if (!name) {
-    console.error(`Account name is required.
+async function accountRemove(names) {
+  if (names.length === 0) {
+    console.error(`At least one account name is required.
 `);
-    console.error("Usage: dot account remove <name>");
+    console.error("Usage: dot account remove <name> [name2] ...");
     process.exit(1);
   }
-  if (isDevAccount(name)) {
-    throw new Error("Cannot remove built-in dev accounts.");
+  const errors = [];
+  for (const name of names) {
+    if (isDevAccount(name)) {
+      errors.push(`Cannot remove built-in dev account "${name}".`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join(`
+`));
   }
   const accountsFile = await loadAccounts();
-  const idx = accountsFile.accounts.findIndex((a) => a.name.toLowerCase() === name.toLowerCase());
-  if (idx === -1) {
-    throw new Error(`Account "${name}" not found.`);
+  const indicesToRemove = new Set;
+  for (const name of names) {
+    const idx = accountsFile.accounts.findIndex((a) => a.name.toLowerCase() === name.toLowerCase());
+    if (idx === -1) {
+      errors.push(`Account "${name}" not found.`);
+    } else {
+      indicesToRemove.add(idx);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join(`
+`));
+  }
+  for (const idx of [...indicesToRemove].sort((a, b) => b - a)) {
+    accountsFile.accounts.splice(idx, 1);
   }
-  accountsFile.accounts.splice(idx, 1);
   await saveAccounts(accountsFile);
-  console.log(`Account "${name}" removed.`);
+  for (const name of names) {
+    console.log(`Account "${name}" removed.`);
+  }
 }
 
 // src/core/client.ts
@@ -560,10 +773,18 @@ class MetadataError extends CliError {
 
 // src/core/client.ts
 var KNOWN_CHAIN_SPECS = {
-  polkadot: "polkadot-api/chains/polkadot",
-  kusama: "polkadot-api/chains/ksmcc3",
-  westend: "polkadot-api/chains/westend2",
-  paseo: "polkadot-api/chains/paseo"
+  polkadot: { spec: "polkadot-api/chains/polkadot" },
+  kusama: { spec: "polkadot-api/chains/ksmcc3" },
+  westend: { spec: "polkadot-api/chains/westend2" },
+  paseo: { spec: "polkadot-api/chains/paseo" },
+  "polkadot-asset-hub": { spec: "polkadot-api/chains/polkadot_asset_hub", relay: "polkadot" },
+  "polkadot-bridge-hub": { spec: "polkadot-api/chains/polkadot_bridge_hub", relay: "polkadot" },
+  "polkadot-collectives": { spec: "polkadot-api/chains/polkadot_collectives", relay: "polkadot" },
+  "polkadot-coretime": { spec: "polkadot-api/chains/polkadot_coretime", relay: "polkadot" },
+  "polkadot-people": { spec: "polkadot-api/chains/polkadot_people", relay: "polkadot" },
+  "paseo-asset-hub": { spec: "polkadot-api/chains/paseo_asset_hub", relay: "paseo" },
+  "paseo-coretime": { spec: "polkadot-api/chains/paseo_coretime", relay: "paseo" },
+  "paseo-people": { spec: "polkadot-api/chains/paseo_people", relay: "paseo" }
 };
 function suppressWsNoise() {
   const orig = console.error;
@@ -607,12 +828,22 @@ async function createChainClient(chainName, chainConfig, rpcOverride) {
 async function createSmoldotProvider(chainName) {
   const { start } = await import("polkadot-api/smoldot");
   const { getSmProvider } = await import("polkadot-api/sm-provider");
-  const specPath = KNOWN_CHAIN_SPECS[chainName];
-  if (!specPath) {
+  const entry = KNOWN_CHAIN_SPECS[chainName];
+  if (!entry) {
     throw new ConnectionError(`Light client is only supported for known chains: ${Object.keys(KNOWN_CHAIN_SPECS).join(", ")}. Use --rpc to connect to "${chainName}" instead.`);
   }
-  const { chainSpec } = await import(specPath);
+  const { chainSpec } = await import(entry.spec);
   const smoldot = start();
+  if (entry.relay) {
+    const relayEntry = KNOWN_CHAIN_SPECS[entry.relay];
+    if (!relayEntry) {
+      throw new ConnectionError(`Relay chain "${entry.relay}" not found in known chain specs.`);
+    }
+    const { chainSpec: relaySpec } = await import(relayEntry.spec);
+    const relayChain = await smoldot.addChain({ chainSpec: relaySpec, disableJsonRpc: true });
+    const chain2 = await smoldot.addChain({ chainSpec, potentialRelayChains: [relayChain] });
+    return getSmProvider(chain2);
+  }
   const chain = await smoldot.addChain({ chainSpec });
   return getSmProvider(chain);
 }
@@ -774,6 +1005,7 @@ ${BOLD}Usage:${RESET}
 
 ${BOLD}Examples:${RESET}
   $ 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
   $ dot chain add westend --light-client
   $ dot chain default kusama
   $ dot chain list
@@ -784,7 +1016,10 @@ ${BOLD}Examples:${RESET}
 function registerChainCommands(cli) {
   cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").alias("chains").action(async (action, name, opts) => {
     if (!action) {
-      return chainList();
+      if (process.argv[2] === "chains")
+        return chainList();
+      console.log(CHAIN_HELP);
+      return;
     }
     switch (action) {
       case "add":
@@ -843,20 +1078,21 @@ async function chainRemove(name) {
     process.exit(1);
   }
   const config = await loadConfig();
-  if (!config.chains[name]) {
+  const resolved = findChainName(config, name);
+  if (!resolved) {
     throw new Error(`Chain "${name}" not found.`);
   }
-  if (name === "polkadot") {
-    throw new Error('Cannot remove the built-in "polkadot" chain.');
+  if (BUILTIN_CHAIN_NAMES.has(resolved)) {
+    throw new Error(`Cannot remove the built-in "${resolved}" chain.`);
   }
-  delete config.chains[name];
-  if (config.defaultChain === name) {
+  delete config.chains[resolved];
+  if (config.defaultChain === resolved) {
     config.defaultChain = "polkadot";
     console.log(`Default chain reset to "polkadot".`);
   }
   await saveConfig(config);
-  await removeChainData(name);
-  console.log(`Chain "${name}" removed.`);
+  await removeChainData(resolved);
+  console.log(`Chain "${resolved}" removed.`);
 }
 async function chainList() {
   const config = await loadConfig();
@@ -864,8 +1100,15 @@ async function chainList() {
   for (const [name, chainConfig] of Object.entries(config.chains)) {
     const isDefault = name === config.defaultChain;
     const marker = isDefault ? ` ${BOLD}(default)${RESET}` : "";
-    const provider = chainConfig.lightClient ? `${DIM}light-client${RESET}` : `${DIM}${chainConfig.rpc}${RESET}`;
-    console.log(`  ${CYAN}${name}${RESET}${marker}  ${provider}`);
+    if (chainConfig.lightClient) {
+      console.log(`  ${CYAN}${name}${RESET}${marker}  ${DIM}light-client${RESET}`);
+    } else {
+      const rpcs = Array.isArray(chainConfig.rpc) ? chainConfig.rpc : [chainConfig.rpc];
+      console.log(`  ${CYAN}${name}${RESET}${marker}  ${DIM}${rpcs[0]}${RESET}`);
+      for (let i = 1;i < rpcs.length; i++) {
+        console.log(`    ${DIM}${rpcs[i]}${RESET}`);
+      }
+    }
   }
   console.log();
 }
@@ -888,13 +1131,14 @@ async function chainDefault(name) {
     process.exit(1);
   }
   const config = await loadConfig();
-  if (!config.chains[name]) {
+  const resolved = findChainName(config, name);
+  if (!resolved) {
     const available = Object.keys(config.chains).join(", ");
     throw new Error(`Chain "${name}" not found. Available: ${available}`);
   }
-  config.defaultChain = name;
+  config.defaultChain = resolved;
   await saveConfig(config);
-  console.log(`Default chain set to "${name}".`);
+  console.log(`Default chain set to "${resolved}".`);
 }
 
 // src/utils/fuzzy-match.ts
@@ -1799,7 +2043,7 @@ function registerTxCommand(cli) {
           }
         }
       }
-      const rpcUrl = opts.rpc ?? chainConfig.rpc;
+      const rpcUrl = primaryRpc(opts.rpc ?? chainConfig.rpc);
       if (rpcUrl) {
         const blockHash = result.block.hash;
         console.log(`  ${BOLD}Explorer:${RESET}`);
@@ -2339,7 +2583,10 @@ import { join as join3 } from "node:path";
 var CACHE_FILE = "update-check.json";
 var STALE_MS = 24 * 60 * 60 * 1000;
 var FETCH_TIMEOUT_MS = 5000;
+var EXIT_WAIT_TIMEOUT_MS = 500;
+var RETRY_AFTER_FAILURE_MS = 60 * 60 * 1000;
 var REGISTRY_URL = "https://registry.npmjs.org/polkadot-cli/latest";
+var pendingCheck = null;
 function parseSemver(v) {
   const clean = v.replace(/^v/, "").split("-")[0] ?? v;
   const parts = clean.split(".").map(Number);
@@ -2405,20 +2652,32 @@ async function writeCache(cache) {
 `);
   } catch {}
 }
-function startBackgroundCheck(_currentVersion) {
+function startBackgroundCheck(currentVersion) {
   const cache = readCache();
   const now = Date.now();
   if (cache && now - cache.lastCheck < STALE_MS) {
     return;
   }
-  fetch(REGISTRY_URL, {
+  pendingCheck = fetch(REGISTRY_URL, {
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
   }).then((res) => res.json()).then((data) => {
     const latestVersion = data.version;
     if (typeof latestVersion === "string") {
-      writeCache({ lastCheck: now, latestVersion });
+      return writeCache({ lastCheck: now, latestVersion });
     }
-  }).catch(() => {});
+  }).catch(() => {
+    return writeCache({
+      lastCheck: now - STALE_MS + RETRY_AFTER_FAILURE_MS,
+      latestVersion: currentVersion
+    });
+  });
+}
+async function waitForPendingCheck() {
+  if (!pendingCheck)
+    return;
+  const timeout = new Promise((resolve) => setTimeout(resolve, EXIT_WAIT_TIMEOUT_MS));
+  await Promise.race([pendingCheck.catch(() => {}), timeout]);
+  pendingCheck = null;
 }
 function getUpdateNotification(currentVersion) {
   if (process.env.DOT_NO_UPDATE_CHECK === "1")
@@ -2460,16 +2719,17 @@ registerConstCommand(cli);
 registerAccountCommands(cli);
 registerTxCommand(cli);
 registerHashCommand(cli);
-cli.help();
+cli.option("--help, -h", "Display this message");
 cli.version(version);
-function showUpdateAndExit(code) {
+async function showUpdateAndExit(code) {
+  await waitForPendingCheck();
   const note = getUpdateNotification(version);
   if (note)
     process.stderr.write(`${note}
 `);
   process.exit(code);
 }
-function handleError(err) {
+async function handleError(err) {
   if (err instanceof CliError2) {
     console.error(`Error: ${err.message}`);
   } else if (err instanceof Error) {
@@ -2477,21 +2737,34 @@ function handleError(err) {
   } else {
     console.error("An unexpected error occurred:", err);
   }
-  showUpdateAndExit(1);
+  return showUpdateAndExit(1);
 }
-try {
-  cli.parse(process.argv, { run: false });
-  if (cli.options.version || cli.options.help) {
-    showUpdateAndExit(0);
-  } else if (!cli.matchedCommandName) {
-    cli.outputHelp();
-    showUpdateAndExit(0);
-  } else {
-    const result = cli.runMatchedCommand();
-    if (result && typeof result.then === "function") {
-      result.then(() => showUpdateAndExit(0), handleError);
+async function main() {
+  try {
+    cli.parse(process.argv, { run: false });
+    if (cli.options.version) {
+      await showUpdateAndExit(0);
+    } else if (cli.options.help) {
+      if (cli.matchedCommandName) {
+        const result = cli.runMatchedCommand();
+        if (result && typeof result.then === "function") {
+          await result.then(() => showUpdateAndExit(0), handleError);
+        }
+      } else {
+        cli.outputHelp();
+        await showUpdateAndExit(0);
+      }
+    } else if (!cli.matchedCommandName) {
+      cli.outputHelp();
+      await showUpdateAndExit(0);
+    } else {
+      const result = cli.runMatchedCommand();
+      if (result && typeof result.then === "function") {
+        await result.then(() => showUpdateAndExit(0), handleError);
+      }
     }
+  } catch (err) {
+    await handleError(err);
   }
-} catch (err) {
-  handleError(err);
 }
+main();

package/package.json

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