polkadot-cli 0.9.0 → 0.11.0

package/README.md

@@ -19,13 +19,16 @@ This installs the `dot` command globally.
 ### Manage chains
 
 ```bash
+# Show chain help
+dot chain               # shows available actions
+dot chains              # shorthand, same as above
+
 # Add a chain
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 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
@@ -42,12 +45,15 @@ dot chain remove westend
 
 Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
 
-> **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.
+> **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
@@ -55,10 +61,28 @@ dot account create my-validator
 # Import from a BIP39 mnemonic
 dot account import treasury --secret "word1 word2 ... word12"
 
+# Import an env-var-backed account (secret stays off disk)
+dot account import ci-signer --env MY_SECRET
+
+# 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
 dot account remove my-validator
 ```
 
+#### Env-var-backed accounts
+
+For CI/CD and security-conscious workflows, store a reference to an environment variable instead of the secret itself:
+
+```bash
+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.
+
 **Supported secret formats for import:**
 
 | Format | Example | Status |
@@ -80,6 +104,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
@@ -298,13 +324,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.9.0";
+var version = "0.11.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -20,11 +20,14 @@ import { join } from "node:path";
 var DEFAULT_CONFIG = {
   defaultChain: "polkadot",
   chains: {
-    polkadot: {
-      rpc: "wss://rpc.polkadot.io"
-    }
+    polkadot: { rpc: "wss://rpc.polkadot.io" },
+    paseo: { rpc: "wss://rpc.ibp.network/paseo" },
+    "polkadot-asset-hub": { rpc: "wss://polkadot-asset-hub-rpc.polkadot.io" },
+    "paseo-asset-hub": { rpc: "wss://asset-hub-paseo-rpc.dwellir.com" },
+    "polkadot-people": { rpc: "wss://polkadot-people-rpc.polkadot.io" }
   }
 };
+var BUILTIN_CHAIN_NAMES = new Set(Object.keys(DEFAULT_CONFIG.chains));
 
 // src/config/store.ts
 var DOT_DIR = join(homedir(), ".polkadot");
@@ -53,8 +56,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 +86,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
@@ -120,6 +131,11 @@ function findAccount(file, name) {
   return file.accounts.find((a) => a.name.toLowerCase() === name.toLowerCase());
 }
 
+// src/config/accounts-types.ts
+function isEnvSecret(secret) {
+  return typeof secret === "object" && secret !== null && "env" in secret;
+}
+
 // src/core/accounts.ts
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd";
 import {
@@ -195,6 +211,27 @@ function toSs58(publicKey, prefix = 42) {
   }
   return ss58Address(publicKey, prefix);
 }
+function resolveSecret(secret) {
+  if (isEnvSecret(secret)) {
+    const value = process.env[secret.env];
+    if (!value) {
+      throw new Error(`Environment variable "${secret.env}" is not set. Set it before signing.`);
+    }
+    return value;
+  }
+  return secret;
+}
+function tryDerivePublicKey(envVarName) {
+  const value = process.env[envVarName];
+  if (!value)
+    return null;
+  try {
+    const { publicKey } = importAccount(value);
+    return publicKeyToHex(publicKey);
+  } catch {
+    return null;
+  }
+}
 async function resolveAccountSigner(name) {
   if (isDevAccount(name)) {
     const keypair2 = getDevKeypair(name);
@@ -206,8 +243,9 @@ async function resolveAccountSigner(name) {
     const available = [...DEV_NAMES, ...accountsFile.accounts.map((a) => a.name)];
     throw new Error(`Unknown account "${name}". Available accounts: ${available.join(", ")}`);
   }
-  const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(account.secret);
-  const keypair = isHexSeed ? deriveFromHexSeed(account.secret, account.derivationPath) : deriveFromMnemonic(account.secret, account.derivationPath);
+  const secret = resolveSecret(account.secret);
+  const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(secret);
+  const keypair = isHexSeed ? deriveFromHexSeed(secret, account.derivationPath) : deriveFromMnemonic(secret, account.derivationPath);
   return getPolkadotSigner(keypair.publicKey, "Sr25519", keypair.sign);
 }
 
@@ -307,32 +345,39 @@ 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 list                         List all accounts
-  $ dot account remove <name>                Remove a stored account
+  $ dot account create|new <name>                       Create a new account
+  $ dot account import|add <name> --secret <s>          Import from BIP39 mnemonic
+  $ dot account import|add <name> --env <VAR>           Import account backed by env variable
+  $ dot account list                                    List all accounts
+  $ dot account remove|delete <name>                    Remove a stored account
 
 ${BOLD}Examples:${RESET}
   $ dot account create my-validator
   $ dot account import treasury --secret "word1 word2 ... word12"
+  $ dot account import ci-signer --env MY_SECRET
   $ dot account list
   $ dot account remove my-validator
 
 ${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, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").action(async (action, name, opts) => {
+  cli.command("account [action] [name]", "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").action(async (action, name, opts) => {
     if (!action) {
-      return accountList();
+      console.log(ACCOUNT_HELP);
+      return;
     }
     switch (action) {
+      case "new":
       case "create":
         return accountCreate(name);
       case "import":
+      case "add":
         return accountImport(name, opts);
       case "list":
         return accountList();
+      case "delete":
       case "remove":
         return accountRemove(name);
       default:
@@ -382,10 +427,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)) {
@@ -395,20 +446,40 @@ 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();
+  if (opts.env) {
+    const publicKey = tryDerivePublicKey(opts.env) ?? "";
+    accountsFile.accounts.push({
+      name,
+      secret: { env: opts.env },
+      publicKey,
+      derivationPath: ""
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Imported");
+    console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+    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);
+    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 accountList() {
   printHeading("Dev Accounts");
@@ -421,8 +492,19 @@ async function accountList() {
   if (accountsFile.accounts.length > 0) {
     printHeading("Stored Accounts");
     for (const account of accountsFile.accounts) {
-      const address = toSs58(account.publicKey);
-      printItem(account.name, address);
+      let displayName = account.name;
+      let address;
+      if (isEnvSecret(account.secret)) {
+        displayName += ` (env: ${account.secret.env})`;
+        let pubKey = account.publicKey;
+        if (!pubKey) {
+          pubKey = tryDerivePublicKey(account.secret.env) ?? "";
+        }
+        address = pubKey ? toSs58(pubKey) : "n/a";
+      } else {
+        address = toSs58(account.publicKey);
+      }
+      printItem(displayName, address);
     }
   } else {
     printHeading("Stored Accounts");
@@ -479,10 +561,13 @@ 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-people": { spec: "polkadot-api/chains/polkadot_people", relay: "polkadot" },
+  "paseo-asset-hub": { spec: "polkadot-api/chains/paseo_asset_hub", relay: "paseo" }
 };
 function suppressWsNoise() {
   const orig = console.error;
@@ -526,12 +611,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);
 }
@@ -703,7 +798,8 @@ ${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();
+      console.log(CHAIN_HELP);
+      return;
     }
     switch (action) {
       case "add":
@@ -762,20 +858,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();
@@ -807,13 +904,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
@@ -2258,7 +2356,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);
@@ -2324,20 +2425,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")
@@ -2381,14 +2494,15 @@ registerTxCommand(cli);
 registerHashCommand(cli);
 cli.help();
 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) {
@@ -2396,21 +2510,24 @@ 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 || cli.options.help) {
+      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.9.0",
+  "version": "0.11.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {