polkadot-cli 0.13.0 → 1.1.0

package/README.md

@@ -220,7 +220,7 @@ dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 # All map entries (default limit: 100)
 dot query System.Account --limit 10
 
-# Pipe to jq — stdout is clean JSON, no extra text
+# Pipe-safe — stdout is clean data, progress messages go to stderr
 dot query System.Account --limit 5 | jq '.[0].value.data.free'
 dot query System.Number --output json | jq '.+1'
 
@@ -249,7 +249,7 @@ dot const Balances.ExistentialDeposit
 dot const System.SS58Prefix --chain kusama
 dot const kusama.Balances.ExistentialDeposit
 
-# Pipe to jq — stdout is clean JSON, no extra text
+# Pipe-safe — stdout is clean JSON, progress messages go to stderr
 dot const Balances.ExistentialDeposit --output json | jq
 ```
 
@@ -258,10 +258,10 @@ dot const Balances.ExistentialDeposit --output json | jq
 Works offline from cached metadata after the first fetch.
 
 ```bash
-# List all pallets (shows storage, constants, and calls counts)
+# List all pallets (shows storage, constants, calls, events, and errors counts)
 dot inspect
 
-# List a pallet's storage items, constants, and calls
+# List a pallet's storage items, constants, calls, events, and errors
 dot inspect System
 
 # Detailed type info for a specific storage item or constant
@@ -270,12 +270,57 @@ dot inspect System.Account
 # Call detail — shows argument signature and docs
 dot inspect Balances.transfer_allow_death
 
+# Event detail — shows field signature and docs
+dot inspect Balances.Transfer
+
+# Error detail — shows docs
+dot inspect Balances.InsufficientBalance
+
 # Inspect a specific chain using chain prefix
 dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
-Use call inspection to discover argument names and types before constructing `dot tx` commands.
+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]`)
+- **Constants**: the constant's type (e.g. `ExistentialDeposit: u128`)
+- **Calls**: full argument signature (e.g. `transfer_allow_death(dest: enum(5 variants), value: Compact<u128>)`)
+- **Events**: field signature (e.g. `Transfer(from: AccountId32, to: AccountId32, amount: u128)`)
+- **Errors**: name and documentation (e.g. `InsufficientBalance`)
+
+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.
+
+### Focused commands
+
+Browse specific metadata categories directly without using `dot inspect`:
+
+```bash
+# List all pallets
+dot pallets
+
+# List pallet calls with argument signatures
+dot calls Balances
+dot calls Balances.transfer_allow_death   # call detail
+
+# List pallet events with field signatures
+dot events Balances
+dot events Balances.Transfer              # event detail
+
+# List pallet errors
+dot errors Balances
+dot errors Balances.InsufficientBalance   # error detail
+
+# List pallet storage items with types
+dot storage System
+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
+```
+
+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`).
 
 ### Submit extrinsics
 
@@ -420,6 +465,24 @@ dot chain --help        # same as `dot chain` — shows chain actions
 dot hash --help         # same as `dot hash` — shows algorithms and examples
 ```
 
+#### Item-level help
+
+Use `--help` on any fully-qualified dot-path to see metadata detail and category-specific usage hints — all offline, no chain connection required:
+
+```bash
+dot tx.System.remark --help               # call args, docs, and tx options
+dot query.System.Account --help           # storage type, key/value info, and query options
+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
+```
+
+For `tx` commands, omitting both `--from` and `--encode` shows this same help output instead of an error:
+
+```bash
+dot tx.System.remark 0xdead               # shows call help (no error)
+```
+
 ### Global options
 
 | Flag | Description |
@@ -431,6 +494,17 @@ dot hash --help         # same as `dot hash` — shows algorithms and examples
 | `--output json` | Raw JSON output (default: pretty) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
 
+### 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:
+
+```bash
+dot const System.SS58Prefix --output json | jq '.+1'
+dot query System.Number --output json | jq
+```
+
+In an interactive terminal, both streams render together so you see progress and results normally.
+
 ## How it compares
 
 | | polkadot-cli | @polkadot/api-cli | subxt-cli | Pop CLI |