polkadot-cli 1.12.0 → 1.13.0

package/README.md

@@ -15,11 +15,12 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ Exposes all on-chain metadata documentation
 - ✅ Encode, dry-run, and submit extrinsics
 - ✅ Support for custom signed extensions
-- ✅ Built with agent use in mind — pipe-safe JSON output (`--output json`)
+- ✅ Built with agent use in mind — structured JSON output on every command (`--json`)
 - ✅ Fuzzy matching with typo suggestions
 - ✅ Account management — BIP39 mnemonics, derivation paths, env-backed secrets, watch-only, dev accounts
 - ✅ Named address resolution across all commands
 - ✅ Runtime API calls — `dot apis.Core.version`
+- ✅ Chain topology — relay/parachain hierarchy with tree display and auto-detection
 - ✅ Batteries included — all system parachains and testnets already setup to be used
 - ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
 - ✅ Parachain sovereign accounts — derive child and sibling addresses from a parachain ID
@@ -28,20 +29,20 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 
 ### 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 |
+| Network | Chain |
+|---------|-------|
+| Polkadot | `polkadot` (relay, default) |
+| | `polkadot-asset-hub` |
+| | `polkadot-bridge-hub` |
+| | `polkadot-collectives` |
+| | `polkadot-coretime` |
+| | `polkadot-people` |
+| Paseo (testnet) | `paseo` (relay) |
+| | `paseo-asset-hub` |
+| | `paseo-bridge-hub` |
+| | `paseo-collectives` |
+| | `paseo-coretime` |
+| | `paseo-people` |
 
 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.
 
@@ -68,10 +69,13 @@ 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
+# Add a parachain under a relay (auto-detects parachain ID)
+dot chain add local-asset-hub --rpc ws://localhost:9945 --relay local-relay
 
-# List configured chains
+# Add a parachain with explicit parachain ID
+dot chain add my-para --rpc wss://rpc.example.com --relay polkadot --parachain-id 2000
+
+# List configured chains (shows relay/parachain hierarchy)
 dot chain list
 
 # Re-fetch metadata after a runtime upgrade
@@ -86,6 +90,31 @@ dot chain default kusama
 dot chain remove westend
 ```
 
+#### Chain topology
+
+`dot chain list` displays chains as a tree, grouping parachains under their parent relay:
+
+```
+Configured Chains
+
+  polkadot (default)  wss://polkadot.ibp.network
+  ├─ polkadot-asset-hub [1000]  wss://...
+  ├─ polkadot-bridge-hub [1002]  wss://...
+  ├─ polkadot-collectives [1001]  wss://...
+  ├─ polkadot-coretime [1005]  wss://...
+  └─ polkadot-people [1004]  wss://...
+
+  paseo  wss://paseo.ibp.network
+  ├─ paseo-asset-hub [1000]  wss://...
+  └─ paseo-people [1004]  wss://...
+
+  my-solo-chain  wss://...
+```
+
+All built-in system parachains are preconfigured with their relay chain and parachain ID. When adding a custom parachain with `--relay`, the CLI auto-detects the parachain ID from on-chain `ParachainInfo` storage. Use `--parachain-id` to set it explicitly if auto-detection is not available.
+
+Removing a relay chain that has parachains prints a warning listing the orphaned chains. The parachains remain in the config and can be re-associated later.
+
 ### Manage accounts
 
 Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
@@ -135,7 +164,7 @@ dot account alice                    # shorthand (same as inspect)
 dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
 dot account inspect alice --prefix 0         # Polkadot mainnet prefix
-dot account inspect alice --output json      # JSON output
+dot account inspect alice --json             # JSON output
 ```
 
 #### Watch-only accounts
@@ -166,7 +195,18 @@ dot query System.Account treasury
 dot tx Balances.transferKeepAlive bob 1000000000000 --from alice
 ```
 
-Resolution order: dev account name > stored account name > SS58 address > hex public key. If the input doesn't match any, the CLI shows an error listing available account names.
+Resolution order: dev account name > stored account name > SS58 address > hex public key. If the input doesn't match any, the CLI shows an error listing all available account names alphabetically, one per line. When the input is close to an existing name, a "Did you mean?" suggestion is included:
+
+```
+Error: Unknown account or address "people-sudo-signer".
+  Did you mean: people-paseo-sudo?
+  Available accounts:
+    - alice
+    - bob
+    - charlie
+    - people-paseo-sudo
+    - ...
+```
 
 #### Inspect accounts
 
@@ -195,7 +235,7 @@ dot account inspect alice --prefix 2     # Kusama (prefix 2)
 JSON output:
 
 ```bash
-dot account inspect alice --output json
+dot account inspect alice --json
 # {"publicKey":"0xd435...a27d","ss58":"5Grw...utQY","prefix":42,"name":"Alice"}
 ```
 
@@ -306,7 +346,7 @@ dot query people-preview.ChunksManager.Chunks R2e9 1
 
 # Pipe-safe — stdout is clean data, progress messages go to stderr
 dot query System.Account --dump | jq '.[0].value.data.free'
-dot query System.Number --output json | jq '.+1'
+dot query System.Number --json | jq '.+1'
 
 # Query a specific chain using chain prefix
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
@@ -351,7 +391,7 @@ dot const System.SS58Prefix --chain kusama
 dot const kusama.Balances.ExistentialDeposit
 
 # Pipe-safe — stdout is clean JSON, progress messages go to stderr
-dot const Balances.ExistentialDeposit --output json | jq
+dot const Balances.ExistentialDeposit --json | jq
 ```
 
 ### Inspect metadata
@@ -525,21 +565,21 @@ Decode a hex-encoded call into a YAML or JSON file that is compatible with [file
 
 ```bash
 # Decode a raw hex call to YAML
-dot tx.0x0001076465616462656566 --yaml
+dot tx.0x0001076465616462656566 --to-yaml
 
 # Decode a raw hex call to JSON
-dot tx.0x0001076465616462656566 --json
+dot tx.0x0001076465616462656566 --to-json
 
 # Encode a named call and output as YAML
-dot tx.System.remark 0xdeadbeef --yaml
+dot tx.System.remark 0xdeadbeef --to-yaml
 
 # Round-trip: encode to hex, decode to YAML, re-encode from file
-dot tx.System.remark 0xdeadbeef --encode           # 0x0001076465616462656566
-dot tx.0x0001076465616462656566 --yaml > remark.yaml
-dot ./remark.yaml --encode                          # same hex
+dot tx.System.remark 0xdeadbeef --encode              # 0x0001076465616462656566
+dot tx.0x0001076465616462656566 --to-yaml > remark.yaml
+dot ./remark.yaml --encode                             # same hex
 ```
 
-`--yaml` / `--json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
+`--to-yaml` / `--to-json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
 
 Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
@@ -627,7 +667,7 @@ Override low-level transaction parameters. Useful for rapid-fire submission (cus
 | `--nonce <n>` | non-negative integer | Override the auto-detected nonce |
 | `--tip <amount>` | non-negative integer (planck) | Priority tip for the transaction pool |
 | `--mortality <spec>` | `immortal` or period (min 4) | Transaction mortality window |
-| `--at <block>` | `best`, `finalized`, or 0x-prefixed block hash | Block state to validate against |
+| `--at <block>` | 0x-prefixed block hash | Block hash to validate against (defaults to finalized) |
 
 ```bash
 # Fire-and-forget: submit two txs in rapid succession with manual nonces
@@ -643,14 +683,14 @@ dot tx System.remark 0xdead --from alice --mortality immortal
 # Set a custom mortality period (rounds up to nearest power of two)
 dot tx System.remark 0xdead --from alice --mortality 128
 
-# Validate against the best (not finalized) block
-dot tx System.remark 0xdead --from alice --at best
+# Validate against a specific block hash
+dot tx System.remark 0xdead --from alice --at 0x1234...abcd
 
 # Combine: rapid-fire with tip and broadcast-only
 dot tx System.remark 0xdead --from alice --nonce 5 --tip 500000 --wait broadcast
 ```
 
-When set, nonce / tip / mortality / at are shown in both `--dry-run` and submission output. These flags are silently ignored with `--encode`, `--yaml`, and `--json` (which return before signing).
+When set, nonce / tip / mortality / at are shown in both `--dry-run` and submission output. These flags are silently ignored with `--encode`, `--to-yaml`, and `--to-json` (which return before signing).
 
 ### File-based commands
 
@@ -837,7 +877,7 @@ CALL=$(dot tx.System.remark 0xdead --encode)
 dot ./xcm-transact.yaml --var CALL=$CALL --encode
 ```
 
-All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--yaml`, `--json`, `--output`, etc. behave identically to inline commands.
+All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--to-yaml`, `--to-json`, `--json`, `--output`, etc. behave identically to inline commands.
 
 ### Compute hashes
 
@@ -857,7 +897,7 @@ dot hash keccak256 --file ./data.bin
 echo -n "hello" | dot hash sha256 --stdin
 
 # JSON output
-dot hash blake2b256 0xdeadbeef --output json
+dot hash blake2b256 0xdeadbeef --json
 ```
 
 Run `dot hash` with no arguments to see all available algorithms.
@@ -880,7 +920,7 @@ dot sign --file ./payload.bin --from alice
 echo -n "hello" | dot sign --stdin --from alice
 
 # JSON output (for scripting)
-dot sign "hello" --from alice --output json
+dot sign "hello" --from alice --json
 ```
 
 Output shows the crypto type, message bytes in hex, raw signature, and an `Enum` value directly pasteable into tx arguments (e.g. `Sr25519(0x...)`).
@@ -908,7 +948,7 @@ dot parachain 2004 --type sibling
 dot parachain 1000 --prefix 0
 
 # JSON output
-dot parachain 1000 --output json
+dot parachain 1000 --json
 ```
 
 Run `dot parachain` with no arguments to see usage and examples.
@@ -928,7 +968,7 @@ dot verifiable alice --context candidate
 dot verifiable alice --context pps
 
 # JSON output (for scripting)
-dot verifiable alice --context candidate --output json
+dot verifiable alice --context candidate --json
 ```
 
 The derivation flow:
@@ -982,18 +1022,46 @@ dot tx.System.remark 0xdead               # shows call help (no error)
 | `--help` | Show help (global or command-specific) |
 | `--chain <name>` | Target chain (default from config) |
 | `--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) |
+
+| `--json` | Structured JSON output (shorthand for `--output json`) |
+| `--output json` | Structured JSON output |
 | `--dump` | Dump all entries of a storage map (required for keyless map queries) |
 | `-w, --wait <level>` | Tx wait level: `broadcast`, `best-block` / `best`, `finalized` (default) |
 
+### Structured JSON output
+
+Every command supports `--json` for machine-readable output. This works on data queries, metadata inspection, account management, chain configuration, and transaction submission:
+
+```bash
+dot inspect --json                          # All pallets as JSON
+dot inspect Balances --json                 # Pallet detail with storage, constants, calls, events, errors
+dot chain list --json                       # Configured chains
+dot account list --json                     # Dev and stored accounts
+dot account create my-key --json            # New account details (mnemonic warning on stderr)
+dot tx.System.remark 0xdead --encode --json # Encoded call hex wrapped in JSON
+dot events.Balances --json                  # Event listing with field signatures
+dot const.System --json                     # Constant listing with types
+```
+
+For transaction submission, `--json` emits NDJSON (one JSON object per lifecycle event):
+
+```bash
+dot tx.System.remark 0xdead --from alice --json
+# {"event":"signed","txHash":"0x..."}
+# {"event":"broadcasted","txHash":"0x..."}
+# {"event":"finalized","blockNumber":123,"blockHash":"0x...","ok":true,"events":[...]}
+```
+
 ### Pipe-safe output
 
-All commands follow Unix conventions: **data goes to stdout, progress goes to stderr**. This means you can safely pipe `--output json` into `jq` or other tools without progress messages ("Fetching metadata...", spinner output, "Connecting...") corrupting the data stream:
+All commands follow Unix conventions: **data goes to stdout, progress goes to stderr**. This means you can safely pipe `--json` into `jq` or other tools without progress messages ("Fetching metadata...", spinner output, "Connecting...") corrupting the data stream:
 
 ```bash
-dot const System.SS58Prefix --output json | jq '.+1'
-dot query System.Number --output json | jq
+dot const System.SS58Prefix --json | jq '.+1'
+dot query System.Number --json | jq
+dot chain list --json | jq '.chains[].name'
+dot account list --json | jq '.stored[].address'
+dot inspect --json | jq '.pallets[] | select(.events > 10) | .name'
 ```
 
 In an interactive terminal, both streams render together so you see progress and results normally.
@@ -1085,7 +1153,7 @@ Config and metadata caches live in `~/.polkadot/`:
 
 ## Environment compatibility
 
-The CLI works in Node.js, Bun, and sandboxed runtimes (e.g. LLM tool-use / MCP environments) that lack a native `globalThis.WebSocket`. WebSocket connections use the [`ws`](https://github.com/websockets/ws) package explicitly, so no global polyfill is required.
+The CLI works in Node.js (v22+), Bun, and sandboxed runtimes (e.g. LLM tool-use / MCP environments). WebSocket connections use the native `WebSocket` implementation provided by the runtime — no external WebSocket package is required.
 
 ## Development