polkadot-cli 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# polkadot-cli
+
+A command-line tool for querying Polkadot-ecosystem on-chain state. Query storage, look up constants, and inspect chain metadata — all from your terminal.
+
+Ships with Polkadot as the default chain. Add any Substrate-based chain by pointing to its RPC endpoint.
+
+## Install
+
+```bash
+npm install -g polkadot-cli
+```
+
+This installs the `dot` command globally.
+
+## Usage
+
+### Query storage
+
+```bash
+# Plain storage value
+dot query System.Number
+
+# Map entry by key
+dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+
+# All map entries (default limit: 100)
+dot query System.Account --limit 10
+
+# Pipe to jq (colors disabled automatically)
+dot query System.Account --limit 5 | jq '.[0].value.data.free'
+```
+
+### Look up constants
+
+```bash
+dot const Balances.ExistentialDeposit
+dot const System.SS58Prefix --chain kusama
+```
+
+### Inspect metadata
+
+Works offline from cached metadata after the first fetch.
+
+```bash
+# List all pallets
+dot inspect
+
+# List a pallet's storage items and constants
+dot inspect System
+
+# Detailed type info for a specific item
+dot inspect System.Account
+```
+
+### Manage chains
+
+```bash
+# Add a chain
+dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+dot chain add westend --light-client
+
+# List configured chains
+dot chain list
+
+# Set default chain
+dot chain default kusama
+
+# Remove a chain
+dot chain remove westend
+```
+
+### Global options
+
+| Flag | Description |
+|------|-------------|
+| `--chain <name>` | Target chain (default from config) |
+| `--rpc <url>` | Override RPC endpoint for this call |
+| `--light-client` | Use Smoldot light client |
+| `--output json` | Raw JSON output (default: pretty) |
+| `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
+
+## Configuration
+
+Config and metadata caches live in `~/.polkadot/`:
+
+```
+~/.polkadot/
+├── config.json          # chains and default chain
+└── chains/
+    └── polkadot/
+        └── metadata.bin # cached SCALE-encoded metadata
+```
+
+## Development
+
+Requires [Bun](https://bun.sh).
+
+```bash
+bun install
+bun run dev -- query System.Number
+bun run build
+bun test
+```
+
+## License
+
+MIT

package/dist/cli.mjs

@@ -0,0 +1,745 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/cli.ts
+import cac from "cac";
+
+// src/config/store.ts
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mkdir, readFile, writeFile, rm, access } from "node:fs/promises";
+
+// src/config/types.ts
+var DEFAULT_CONFIG = {
+  defaultChain: "polkadot",
+  chains: {
+    polkadot: {
+      rpc: "wss://rpc.polkadot.io"
+    }
+  }
+};
+
+// src/config/store.ts
+var DOT_DIR = join(homedir(), ".polkadot");
+var CONFIG_PATH = join(DOT_DIR, "config.json");
+var CHAINS_DIR = join(DOT_DIR, "chains");
+function getChainDir(chainName) {
+  return join(CHAINS_DIR, chainName);
+}
+function getMetadataPath(chainName) {
+  return join(CHAINS_DIR, chainName, "metadata.bin");
+}
+async function ensureDir(dir) {
+  await mkdir(dir, { recursive: true });
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function loadConfig() {
+  await ensureDir(DOT_DIR);
+  if (await fileExists(CONFIG_PATH)) {
+    const data = await readFile(CONFIG_PATH, "utf-8");
+    return JSON.parse(data);
+  }
+  await saveConfig(DEFAULT_CONFIG);
+  return DEFAULT_CONFIG;
+}
+async function saveConfig(config) {
+  await ensureDir(DOT_DIR);
+  await writeFile(CONFIG_PATH, JSON.stringify(config, null, 2) + `
+`);
+}
+async function loadMetadata(chainName) {
+  const path = getMetadataPath(chainName);
+  if (await fileExists(path)) {
+    return await readFile(path);
+  }
+  return null;
+}
+async function saveMetadata(chainName, data) {
+  const dir = getChainDir(chainName);
+  await ensureDir(dir);
+  await writeFile(getMetadataPath(chainName), data);
+}
+async function removeChainData(chainName) {
+  const dir = getChainDir(chainName);
+  await rm(dir, { recursive: true, force: true });
+}
+function resolveChain(config, chainFlag) {
+  const name = chainFlag ?? config.defaultChain;
+  const chain = config.chains[name];
+  if (!chain) {
+    const available = Object.keys(config.chains).join(", ");
+    throw new Error(`Unknown chain "${name}". Available chains: ${available}`);
+  }
+  return { name, chain };
+}
+
+// src/core/client.ts
+import { createClient } from "polkadot-api";
+import { getWsProvider } from "polkadot-api/ws-provider";
+import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
+
+// src/utils/errors.ts
+class CliError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+class ConnectionError extends CliError {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionError";
+  }
+}
+
+class MetadataError extends CliError {
+  constructor(message) {
+    super(message);
+    this.name = "MetadataError";
+  }
+}
+
+// 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"
+};
+async function createChainClient(chainName, chainConfig, rpcOverride) {
+  const useLight = !rpcOverride && chainConfig.lightClient;
+  let provider;
+  if (useLight) {
+    provider = await createSmoldotProvider(chainName);
+  } else {
+    const rpc = rpcOverride ?? chainConfig.rpc;
+    if (!rpc) {
+      throw new ConnectionError(`No RPC endpoint configured for chain "${chainName}". Use --rpc or configure one with: dot chain add ${chainName} --rpc <url>`);
+    }
+    provider = withPolkadotSdkCompat(getWsProvider(rpc));
+  }
+  const client = createClient(provider, {
+    getMetadata: async () => loadMetadata(chainName),
+    setMetadata: async (_codeHash, metadata) => {
+      await saveMetadata(chainName, metadata);
+    }
+  });
+  return {
+    client,
+    destroy: () => client.destroy()
+  };
+}
+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) {
+    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 smoldot = start();
+  const chain = await smoldot.addChain({ chainSpec });
+  return getSmProvider(chain);
+}
+
+// src/core/metadata.ts
+import {
+  decAnyMetadata,
+  unifyMetadata
+} from "@polkadot-api/substrate-bindings";
+import { getLookupFn, getDynamicBuilder } from "@polkadot-api/metadata-builders";
+function parseMetadata(raw) {
+  const decoded = decAnyMetadata(raw);
+  const unified = unifyMetadata(decoded);
+  const lookup = getLookupFn(unified);
+  const builder = getDynamicBuilder(lookup);
+  return { unified, lookup, builder };
+}
+async function fetchMetadataFromChain(clientHandle, chainName) {
+  const { client } = clientHandle;
+  const hex = await client._request("state_getMetadata", []);
+  const bytes = hexToBytes(hex);
+  await saveMetadata(chainName, bytes);
+  return bytes;
+}
+async function getOrFetchMetadata(chainName, clientHandle) {
+  let raw = await loadMetadata(chainName);
+  if (!raw) {
+    if (!clientHandle) {
+      throw new MetadataError(`No cached metadata for chain "${chainName}". Run a command that connects to the chain first, ` + `e.g.: dot chain add ${chainName} --rpc <url>`);
+    }
+    raw = await fetchMetadataFromChain(clientHandle, chainName);
+  }
+  return parseMetadata(raw);
+}
+function listPallets(meta) {
+  return meta.unified.pallets.map((p) => ({
+    name: p.name,
+    index: p.index,
+    docs: p.docs ?? [],
+    storage: (p.storage?.items ?? []).map((s) => ({
+      name: s.name,
+      docs: s.docs ?? [],
+      type: s.type.tag,
+      keyTypeId: s.type.tag === "map" ? s.type.value.key : null,
+      valueTypeId: s.type.tag === "plain" ? s.type.value : s.type.value.value
+    })),
+    constants: (p.constants ?? []).map((c) => ({
+      name: c.name,
+      docs: c.docs ?? [],
+      typeId: c.type
+    }))
+  }));
+}
+function findPallet(meta, palletName) {
+  const pallets = listPallets(meta);
+  return pallets.find((p) => p.name.toLowerCase() === palletName.toLowerCase());
+}
+function getPalletNames(meta) {
+  return meta.unified.pallets.map((p) => p.name);
+}
+function describeType(lookup, typeId) {
+  try {
+    const entry = lookup(typeId);
+    return formatLookupEntry(entry);
+  } catch {
+    return `type(${typeId})`;
+  }
+}
+function formatLookupEntry(entry) {
+  switch (entry.type) {
+    case "primitive":
+      return entry.value;
+    case "compact":
+      return `Compact<${formatLookupEntry(entry.isBig ? { type: "primitive", value: "u128" } : { type: "primitive", value: "u64" })}>`;
+    case "AccountId32":
+      return "AccountId32";
+    case "bitSequence":
+      return "BitSequence";
+    case "sequence":
+      return `Vec<${formatLookupEntry(entry.value)}>`;
+    case "array":
+      return `[${formatLookupEntry(entry.value)}; ${entry.len}]`;
+    case "tuple":
+      return `(${entry.value.map(formatLookupEntry).join(", ")})`;
+    case "struct":
+      return `{ ${Object.entries(entry.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ")} }`;
+    case "option":
+      return `Option<${formatLookupEntry(entry.value)}>`;
+    case "result":
+      return `Result<${formatLookupEntry(entry.value.ok)}, ${formatLookupEntry(entry.value.ko)}>`;
+    case "enum": {
+      const variants = Object.keys(entry.value);
+      if (variants.length <= 4)
+        return variants.join(" | ");
+      return `enum(${variants.length} variants)`;
+    }
+    default:
+      return "unknown";
+  }
+}
+function hexToBytes(hex) {
+  const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const bytes = new Uint8Array(clean.length / 2);
+  for (let i = 0;i < clean.length; i += 2) {
+    bytes[i / 2] = parseInt(clean.substring(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+// src/core/output.ts
+var isTTY = process.stdout.isTTY ?? false;
+var RESET = isTTY ? "\x1B[0m" : "";
+var CYAN = isTTY ? "\x1B[36m" : "";
+var GREEN = isTTY ? "\x1B[32m" : "";
+var YELLOW = isTTY ? "\x1B[33m" : "";
+var MAGENTA = isTTY ? "\x1B[35m" : "";
+var DIM = isTTY ? "\x1B[2m" : "";
+var BOLD = isTTY ? "\x1B[1m" : "";
+function replacer(_key, value) {
+  if (typeof value === "bigint")
+    return value.toString();
+  if (value instanceof Uint8Array)
+    return "0x" + Buffer.from(value).toString("hex");
+  return value;
+}
+function formatJson(data) {
+  return JSON.stringify(data, replacer, 2);
+}
+function formatPretty(data) {
+  const json = JSON.stringify(data, replacer, 2);
+  if (!json)
+    return "undefined";
+  return colorizeJson(json);
+}
+function colorizeJson(json) {
+  return json.replace(/("(?:\\.|[^"\\])*")\s*:/g, `${CYAN}$1${RESET}:`).replace(/:\s*("(?:\\.|[^"\\])*")/g, (match, str) => match.replace(str, `${GREEN}${str}${RESET}`)).replace(/:\s*(\d+(?:\.\d+)?)/g, (match, num) => match.replace(num, `${YELLOW}${num}${RESET}`)).replace(/:\s*(true|false)/g, (match, bool) => match.replace(bool, `${MAGENTA}${bool}${RESET}`)).replace(/:\s*(null)/g, (match, n) => match.replace(n, `${DIM}${n}${RESET}`));
+}
+function printResult(data, format = "pretty") {
+  if (format === "json") {
+    console.log(formatJson(data));
+  } else {
+    console.log(formatPretty(data));
+  }
+}
+function printHeading(text) {
+  console.log(`
+${BOLD}${text}${RESET}
+`);
+}
+function printItem(name, description) {
+  if (description) {
+    console.log(`  ${CYAN}${name}${RESET}  ${DIM}${description}${RESET}`);
+  } else {
+    console.log(`  ${CYAN}${name}${RESET}`);
+  }
+}
+function printDocs(docs) {
+  const text = docs.join(`
+`).trim();
+  if (text) {
+    console.log(`  ${DIM}${text}${RESET}`);
+  }
+}
+
+// src/commands/chain.ts
+var CHAIN_HELP = `
+${BOLD}Usage:${RESET}
+  $ dot chain add <name> --rpc <url>    Add a chain via WebSocket RPC
+  $ dot chain add <name> --light-client Add a chain via Smoldot light client
+  $ dot chain remove <name>             Remove a chain
+  $ dot chain list                      List configured chains
+  $ dot chain default <name>            Set the default chain
+
+${BOLD}Examples:${RESET}
+  $ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+  $ dot chain add westend --light-client
+  $ dot chain default kusama
+  $ dot chain list
+  $ dot chain remove kusama
+`.trimStart();
+function registerChainCommands(cli) {
+  cli.command("chain [action] [name]", "Manage chains (add, remove, list, default)").action(async (action, name, opts) => {
+    if (!action) {
+      console.log(CHAIN_HELP);
+      return;
+    }
+    switch (action) {
+      case "add":
+        return chainAdd(name, opts);
+      case "remove":
+        return chainRemove(name);
+      case "list":
+        return chainList();
+      case "default":
+        return chainDefault(name);
+      default:
+        console.error(`Unknown action "${action}".
+`);
+        console.log(CHAIN_HELP);
+        process.exit(1);
+    }
+  });
+}
+async function chainAdd(name, opts) {
+  if (!name) {
+    console.error(`Chain name is required.
+`);
+    console.error("Usage: dot chain add <name> --rpc <url>");
+    console.error("       dot chain add <name> --light-client");
+    process.exit(1);
+  }
+  if (!opts.rpc && !opts.lightClient) {
+    console.error(`Must provide either --rpc <url> or --light-client.
+`);
+    console.error("Usage: dot chain add <name> --rpc <url>");
+    console.error("       dot chain add <name> --light-client");
+    process.exit(1);
+  }
+  const config = await loadConfig();
+  config.chains[name] = {
+    rpc: opts.rpc ?? "",
+    ...opts.lightClient ? { lightClient: true } : {}
+  };
+  await saveConfig(config);
+  console.log(`Connecting to ${name}...`);
+  const clientHandle = await createChainClient(name, config.chains[name], opts.rpc);
+  try {
+    console.log("Fetching metadata...");
+    await fetchMetadataFromChain(clientHandle, name);
+    console.log(`Chain "${name}" added successfully.`);
+  } finally {
+    clientHandle.destroy();
+  }
+}
+async function chainRemove(name) {
+  if (!name) {
+    console.error("Usage: dot chain remove <name>");
+    process.exit(1);
+  }
+  const config = await loadConfig();
+  if (!config.chains[name]) {
+    throw new Error(`Chain "${name}" not found.`);
+  }
+  if (name === "polkadot") {
+    throw new Error('Cannot remove the built-in "polkadot" chain.');
+  }
+  delete config.chains[name];
+  if (config.defaultChain === name) {
+    config.defaultChain = "polkadot";
+    console.log(`Default chain reset to "polkadot".`);
+  }
+  await saveConfig(config);
+  await removeChainData(name);
+  console.log(`Chain "${name}" removed.`);
+}
+async function chainList() {
+  const config = await loadConfig();
+  printHeading("Configured Chains");
+  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}`);
+  }
+  console.log();
+}
+async function chainDefault(name) {
+  if (!name) {
+    console.error("Usage: dot chain default <name>");
+    process.exit(1);
+  }
+  const config = await loadConfig();
+  if (!config.chains[name]) {
+    const available = Object.keys(config.chains).join(", ");
+    throw new Error(`Chain "${name}" not found. Available: ${available}`);
+  }
+  config.defaultChain = name;
+  await saveConfig(config);
+  console.log(`Default chain set to "${name}".`);
+}
+
+// src/utils/parse-target.ts
+function parseTarget(input) {
+  const parts = input.split(".");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`Invalid target "${input}". Expected format: Pallet.Item (e.g. System.Account)`);
+  }
+  return { pallet: parts[0], item: parts[1] };
+}
+
+// src/utils/fuzzy-match.ts
+function levenshtein(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  const dp = Array.from({ length: la + 1 }, () => Array(lb + 1).fill(0));
+  for (let i = 0;i <= la; i++)
+    dp[i][0] = i;
+  for (let j = 0;j <= lb; j++)
+    dp[0][j] = j;
+  for (let i = 1;i <= la; i++) {
+    for (let j = 1;j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+    }
+  }
+  return dp[la][lb];
+}
+function findClosest(input, candidates, maxDistance = 3) {
+  const lower = input.toLowerCase();
+  const exact = candidates.find((c) => c.toLowerCase() === lower);
+  if (exact)
+    return [exact];
+  const scored = candidates.map((c) => ({ name: c, dist: levenshtein(lower, c.toLowerCase()) })).filter((s) => s.dist <= maxDistance).sort((a, b) => a.dist - b.dist);
+  return scored.slice(0, 3).map((s) => s.name);
+}
+function suggestMessage(kind, input, candidates) {
+  const suggestions = findClosest(input, candidates);
+  if (suggestions.length === 0) {
+    return `Unknown ${kind} "${input}".`;
+  }
+  if (suggestions.length === 1 && suggestions[0].toLowerCase() === input.toLowerCase()) {
+    return suggestions[0];
+  }
+  return `Unknown ${kind} "${input}". Did you mean: ${suggestions.join(", ")}?`;
+}
+
+// src/commands/inspect.ts
+function registerInspectCommand(cli) {
+  cli.command("inspect [target]", "Inspect chain metadata (pallets, storage, constants)").option("--chain <name>", "Target chain").option("--rpc <url>", "Override RPC endpoint").action(async (target, opts) => {
+    const config = await loadConfig();
+    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
+    let meta;
+    try {
+      meta = await getOrFetchMetadata(chainName);
+    } catch {
+      console.log(`Fetching metadata from ${chainName}...`);
+      const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
+      try {
+        meta = await getOrFetchMetadata(chainName, clientHandle);
+      } finally {
+        clientHandle.destroy();
+      }
+    }
+    if (!target) {
+      const pallets = listPallets(meta);
+      printHeading(`Pallets on ${chainName} (${pallets.length})`);
+      for (const p of pallets) {
+        const counts = [];
+        if (p.storage.length)
+          counts.push(`${p.storage.length} storage`);
+        if (p.constants.length)
+          counts.push(`${p.constants.length} constants`);
+        printItem(p.name, counts.join(", "));
+      }
+      console.log();
+      return;
+    }
+    if (!target.includes(".")) {
+      const palletNames2 = getPalletNames(meta);
+      const pallet2 = findPallet(meta, target);
+      if (!pallet2) {
+        throw new Error(suggestMessage("pallet", target, palletNames2));
+      }
+      printHeading(`${pallet2.name} Pallet`);
+      if (pallet2.docs.length) {
+        printDocs(pallet2.docs);
+        console.log();
+      }
+      if (pallet2.storage.length) {
+        console.log(`  ${BOLD}Storage Items:${RESET}`);
+        for (const s of pallet2.storage) {
+          const doc = s.docs[0] ? ` — ${s.docs[0].slice(0, 80)}` : "";
+          console.log(`    ${CYAN}${s.name}${RESET}${DIM}${doc}${RESET}`);
+        }
+        console.log();
+      }
+      if (pallet2.constants.length) {
+        console.log(`  ${BOLD}Constants:${RESET}`);
+        for (const c of pallet2.constants) {
+          const doc = c.docs[0] ? ` — ${c.docs[0].slice(0, 80)}` : "";
+          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${doc}${RESET}`);
+        }
+        console.log();
+      }
+      return;
+    }
+    const { pallet: palletName, item: itemName } = parseTarget(target);
+    const palletNames = getPalletNames(meta);
+    const pallet = findPallet(meta, palletName);
+    if (!pallet) {
+      throw new Error(suggestMessage("pallet", palletName, palletNames));
+    }
+    const storageItem = pallet.storage.find((s) => s.name.toLowerCase() === itemName.toLowerCase());
+    if (storageItem) {
+      printHeading(`${pallet.name}.${storageItem.name} (Storage)`);
+      console.log(`  ${BOLD}Type:${RESET} ${storageItem.type}`);
+      console.log(`  ${BOLD}Value:${RESET} ${describeType(meta.lookup, storageItem.valueTypeId)}`);
+      if (storageItem.keyTypeId != null) {
+        console.log(`  ${BOLD}Key:${RESET} ${describeType(meta.lookup, storageItem.keyTypeId)}`);
+      }
+      if (storageItem.docs.length) {
+        console.log();
+        printDocs(storageItem.docs);
+      }
+      console.log();
+      return;
+    }
+    const constantItem = pallet.constants.find((c) => c.name.toLowerCase() === itemName.toLowerCase());
+    if (constantItem) {
+      printHeading(`${pallet.name}.${constantItem.name} (Constant)`);
+      console.log(`  ${BOLD}Type:${RESET} ${describeType(meta.lookup, constantItem.typeId)}`);
+      if (constantItem.docs.length) {
+        console.log();
+        printDocs(constantItem.docs);
+      }
+      console.log();
+      return;
+    }
+    const allItems = [
+      ...pallet.storage.map((s) => s.name),
+      ...pallet.constants.map((c) => c.name)
+    ];
+    throw new Error(suggestMessage(`item in ${pallet.name}`, itemName, allItems));
+  });
+}
+
+// src/commands/query.ts
+var DEFAULT_LIMIT = 100;
+function registerQueryCommand(cli) {
+  cli.command("query [target] [...keys]", "Query on-chain storage (e.g. System.Number, System.Account <addr>)").option("--limit <n>", "Max entries to return for map queries (0 = unlimited)", {
+    default: DEFAULT_LIMIT
+  }).action(async (target, keys, opts) => {
+    if (!target) {
+      console.log("Usage: dot query <Pallet.Item> [...keys] [--chain <name>] [--output json]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot query System.Number                         # plain storage value");
+      console.log("  $ dot query System.Account 5Grw...                # single map entry");
+      console.log("  $ dot query System.Account                        # all entries (limit 100)");
+      console.log("  $ dot query System.Account --limit 10             # first 10 entries");
+      console.log("  $ dot query System.Account --limit 0              # all entries (no limit)");
+      console.log("  $ dot query Assets.Metadata 42 --chain asset-hub");
+      return;
+    }
+    const config = await loadConfig();
+    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
+    const { pallet, item } = parseTarget(target);
+    const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
+    try {
+      const meta = await getOrFetchMetadata(chainName, clientHandle);
+      const palletNames = getPalletNames(meta);
+      const palletInfo = findPallet(meta, pallet);
+      if (!palletInfo) {
+        throw new Error(suggestMessage("pallet", pallet, palletNames));
+      }
+      const storageItem = palletInfo.storage.find((s) => s.name.toLowerCase() === item.toLowerCase());
+      if (!storageItem) {
+        const storageNames = palletInfo.storage.map((s) => s.name);
+        throw new Error(suggestMessage(`storage item in ${palletInfo.name}`, item, storageNames));
+      }
+      const unsafeApi = clientHandle.client.getUnsafeApi();
+      const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
+      const parsedKeys = keys.map(parseKeyArg);
+      const format = opts.output ?? "pretty";
+      if (storageItem.type === "map" && parsedKeys.length === 0) {
+        const entries = await storageApi.getEntries();
+        const limit = Number(opts.limit);
+        const truncated = limit > 0 && entries.length > limit;
+        const display = truncated ? entries.slice(0, limit) : entries;
+        printResult(display.map((e) => ({
+          keys: e.keyArgs,
+          value: e.value
+        })), format);
+        if (truncated) {
+          console.error(`
+${DIM}Showing ${limit} of ${entries.length} entries. Use --limit 0 for all.${RESET}`);
+        }
+      } else {
+        const result = await storageApi.getValue(...parsedKeys);
+        printResult(result, format);
+      }
+    } finally {
+      clientHandle.destroy();
+    }
+  });
+}
+function parseKeyArg(arg) {
+  if (/^\d+$/.test(arg))
+    return parseInt(arg, 10);
+  if (/^\d{16,}$/.test(arg))
+    return BigInt(arg);
+  if (/^0x[0-9a-fA-F]+$/.test(arg))
+    return arg;
+  if (arg === "true")
+    return true;
+  if (arg === "false")
+    return false;
+  if (arg.startsWith("{") || arg.startsWith("[")) {
+    try {
+      return JSON.parse(arg);
+    } catch {}
+  }
+  return arg;
+}
+
+// src/commands/const.ts
+function registerConstCommand(cli) {
+  cli.command("const [target]", "Look up a pallet constant (e.g. Balances.ExistentialDeposit)").action(async (target, opts) => {
+    if (!target) {
+      console.log("Usage: dot const <Pallet.Constant> [--chain <name>] [--output json]");
+      console.log("");
+      console.log("Examples:");
+      console.log("  $ dot const Balances.ExistentialDeposit");
+      console.log("  $ dot const System.SS58Prefix --chain kusama");
+      return;
+    }
+    const config = await loadConfig();
+    const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
+    const { pallet, item } = parseTarget(target);
+    const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
+    try {
+      const meta = await getOrFetchMetadata(chainName, clientHandle);
+      const palletNames = getPalletNames(meta);
+      const palletInfo = findPallet(meta, pallet);
+      if (!palletInfo) {
+        throw new Error(suggestMessage("pallet", pallet, palletNames));
+      }
+      const constantItem = palletInfo.constants.find((c) => c.name.toLowerCase() === item.toLowerCase());
+      if (!constantItem) {
+        const constNames = palletInfo.constants.map((c) => c.name);
+        throw new Error(suggestMessage(`constant in ${palletInfo.name}`, item, constNames));
+      }
+      const unsafeApi = clientHandle.client.getUnsafeApi();
+      const runtimeToken = await unsafeApi.runtimeToken;
+      const result = unsafeApi.constants[palletInfo.name][constantItem.name](runtimeToken);
+      printResult(result, opts.output ?? "pretty");
+    } finally {
+      clientHandle.destroy();
+    }
+  });
+}
+
+// src/utils/errors.ts
+class CliError2 extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliError";
+  }
+}
+
+// src/cli.ts
+var cli = cac("dot");
+cli.option("--chain <name>", "Target chain (default from config)");
+cli.option("--rpc <url>", "Override RPC endpoint for this call");
+cli.option("--light-client", "Use Smoldot light client instead of WebSocket");
+cli.option("--output <format>", "Output format: pretty or json", {
+  default: "pretty"
+});
+registerChainCommands(cli);
+registerInspectCommand(cli);
+registerQueryCommand(cli);
+registerConstCommand(cli);
+cli.help();
+cli.version("0.1.0");
+function handleError(err) {
+  if (err instanceof CliError2) {
+    console.error(`Error: ${err.message}`);
+  } else if (err instanceof Error) {
+    console.error(`Error: ${err.message}`);
+  } else {
+    console.error("An unexpected error occurred:", err);
+  }
+  process.exit(1);
+}
+process.on("unhandledRejection", handleError);
+try {
+  cli.parse();
+} catch (err) {
+  handleError(err);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "polkadot-cli",
+  "version": "0.1.0",
+  "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
+  "type": "module",
+  "bin": {
+    "dot": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "bun src/cli.ts",
+    "build": "bun build src/cli.ts --outfile dist/cli.mjs --target node --packages external && bun run build:shebang",
+    "build:shebang": "bun -e \"const f='dist/cli.mjs'; const s=await Bun.file(f).text(); await Bun.write(f, s.replace('#!/usr/bin/env bun', '#!/usr/bin/env node').replace('// @bun\\n',''))\"",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "license": "MIT",
+  "keywords": [
+    "polkadot",
+    "substrate",
+    "blockchain",
+    "cli",
+    "web3"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/peetzweg/polkadot-cli"
+  },
+  "dependencies": {
+    "cac": "^6.7.14",
+    "polkadot-api": "^1.23.3",
+    "@polkadot-api/metadata-builders": "^0.13.9",
+    "@polkadot-api/substrate-bindings": "^0.17.0",
+    "@polkadot-api/view-builder": "^0.4.17"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.4",
+    "@types/bun": "latest"
+  }
+}