polkadot-cli 1.4.0 → 1.6.0

package/README.md

@@ -6,6 +6,21 @@ A command-line tool for interacting with Polkadot-ecosystem chains. Manage chain
 
 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).
 
+## Features
+
+- ✅ Same syntax as [polkadot-api](https://papi.how) (PAPI)
+- ✅ Chain name prefix — `dot polkadot.query.System.Number`
+- ✅ zsh, bash, and fish autocompletion
+- ✅ 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`)
+- ✅ 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`
+- ✅ Batteries included — all system parachains and testnets already setup to be used
+
 ### Preconfigured chains
 
 | Network | Chain | Light client |
@@ -57,6 +72,7 @@ dot chain list
 # Re-fetch metadata after a runtime upgrade
 dot chain update          # updates default chain
 dot chain update kusama   # updates a specific chain
+dot chain update --all    # updates all configured chains in parallel
 
 # Set default chain
 dot chain default kusama
@@ -321,6 +337,8 @@ dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
+All listings — pallets, storage items, constants, calls, events, and errors — are sorted alphabetically, making it easy to find a specific item at a glance.
+
 The pallet listing view shows type information inline so you can understand item shapes at a glance:
 
 - **Storage**: key/value types with `[map]` tag for map items (e.g. `Account: AccountId32 → { nonce: u32, ... }    [map]`)
@@ -331,6 +349,37 @@ The pallet listing view shows type information inline so you can understand item
 
 Documentation from the runtime metadata is shown on an indented line below each item. The detail view (`dot inspect Balances.transfer_allow_death`) shows the full argument signature and complete documentation text. Use call inspection to discover argument names, types, and docs before constructing `dot tx` commands.
 
+### Runtime APIs
+
+Browse and call Substrate runtime APIs. These are top-level APIs exposed by the runtime (e.g. `Core`, `AccountNonceApi`, `TransactionPaymentApi`), accessed as `dot apis.ApiName.method`.
+
+```bash
+# List all runtime APIs with method counts
+dot apis
+
+# List methods in a specific API (with signatures)
+dot apis.Core
+
+# Call a runtime API method
+dot apis.Core.version
+
+# With chain prefix
+dot polkadot.apis.Core.version
+
+# Show method signature and docs
+dot apis.Core.version --help
+```
+
+`api` is an alias for `apis`.
+
+Runtime API info requires v15 metadata. If `dot apis` shows 0 APIs, update the cached metadata:
+
+```bash
+dot chain update              # default chain
+dot chain update people-paseo # specific chain
+dot chain update --all        # all configured chains
+```
+
 ### Focused commands
 
 Browse specific metadata categories directly without using `dot inspect`:
@@ -358,9 +407,13 @@ dot storage System.Account               # storage detail
 # List pallet constants (dual-purpose — also works as value lookup)
 dot const Balances                        # list constants
 dot const Balances.ExistentialDeposit     # look up value
+
+# List runtime APIs
+dot apis                                  # list all APIs
+dot apis.Core                             # list methods in Core
 ```
 
-Each command supports `--chain <name>`, `--rpc <url>`, and chain prefix syntax. Singular and plural forms are interchangeable (e.g. `dot call` = `dot calls`, `dot event` = `dot events`).
+Each command supports `--chain <name>`, `--rpc <url>`, and chain prefix syntax. Singular and plural forms are interchangeable (e.g. `dot call` = `dot calls`, `dot event` = `dot events`, `dot api` = `dot apis`).
 
 ### Submit extrinsics
 
@@ -457,6 +510,31 @@ dot tx Balances.transferKeepAlive 5GrwvaEF... abc --encode
 
 For struct-based calls, the error identifies the specific field that failed. For tuple-based calls, it shows the argument index. The original parse error is preserved as the `cause` for programmatic access.
 
+#### Wait level
+
+By default, `dot tx` waits for finalization (~30s on Polkadot). Use `--wait` / `-w` to return earlier:
+
+```bash
+# Return as soon as the tx is broadcast (fastest)
+dot tx System.remark 0xdead --from alice --wait broadcast
+
+# Return when included in a best block
+dot tx System.remark 0xdead --from alice -w best-block
+dot tx System.remark 0xdead --from alice -w best    # alias
+
+# Wait for finalization (default, unchanged)
+dot tx System.remark 0xdead --from alice --wait finalized
+dot tx System.remark 0xdead --from alice             # same
+```
+
+| Level | Resolves when | Events shown | Explorer links |
+|-------|---------------|:---:|:---:|
+| `broadcast` | Tx is broadcast to the network | — | — |
+| `best-block` / `best` | Tx is included in a best block | yes | yes |
+| `finalized` (default) | Tx is finalized | yes | yes |
+
+The `--wait` flag is silently ignored when combined with `--dry-run` or `--encode` (both return before submission).
+
 #### Custom signed extensions
 
 Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:
@@ -515,6 +593,7 @@ dot query.System.Account --help           # storage type, key/value info, and qu
 dot const.Balances.ExistentialDeposit --help  # constant type and docs
 dot events.Balances.Transfer --help       # event fields and docs
 dot errors.Balances.InsufficientBalance --help  # error docs
+dot apis.Core.version --help             # runtime API method signature and docs
 ```
 
 For `tx` commands, omitting both `--from` and `--encode` shows this same help output instead of an error:
@@ -534,6 +613,7 @@ dot tx.System.remark 0xdead               # shows call help (no error)
 | `--output json` | Raw JSON output (default: pretty) |
 | `--dump` | Dump all entries of a storage map (required for keyless map queries) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
+| `-w, --wait <level>` | Tx wait level: `broadcast`, `best-block` / `best`, `finalized` (default) |
 
 ### Pipe-safe output
 
@@ -567,13 +647,15 @@ Once installed, press Tab to complete:
 dot qu<Tab>              # → query
 dot query.<Tab>          # → query.System, query.Balances, ...
 dot query.System.<Tab>   # → query.System.Account, query.System.Number, ...
-dot polkadot.<Tab>       # → polkadot.query, polkadot.tx, ...
+dot apis.<Tab>           # → apis.Core, apis.Metadata, ...
+dot apis.Core.<Tab>      # → apis.Core.version, ...
+dot polkadot.<Tab>       # → polkadot.query, polkadot.tx, ..., polkadot.apis
 dot --chain <Tab>        # → polkadot, paseo, ...
 dot --from <Tab>         # → alice, bob, ..., stored account names
 dot chain <Tab>          # → add, remove, update, list, default
 ```
 
-Completions are context-aware: `query.` shows pallets with storage items, `tx.` shows pallets with calls, `events.` and `errors.` filter accordingly. Chain prefix paths like `polkadot.query.System.` work at any depth.
+Completions are context-aware: `query.` shows pallets with storage items, `tx.` shows pallets with calls, `events.` and `errors.` filter accordingly, `apis.` shows runtime API names. Chain prefix paths like `polkadot.query.System.` work at any depth.
 
 ## How it compares