polkadot-cli 0.5.0 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # polkadot-cli
 
-A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, and submit extrinsics — all from your terminal.
+A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from your terminal.
 
 Ships with Polkadot as the default chain. Add any Substrate-based chain by pointing to its RPC endpoint.
 
@@ -39,6 +39,8 @@ 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.
+
 ```bash
 # List all accounts (dev + stored)
 dot account list
@@ -49,13 +51,19 @@ dot account create my-validator
 # Import from a BIP39 mnemonic
 dot account import treasury --secret "word1 word2 ... word12"
 
-# Import from a hex seed
-dot account import raw-key --secret 0xabcdef...
-
 # Remove an account
 dot account remove my-validator
 ```
 
+**Supported secret formats for import:**
+
+| Format | Example | Status |
+|--------|---------|--------|
+| BIP39 mnemonic (12/24 words) | `"abandon abandon ... about"` | Supported |
+| Hex seed (`0x` + 64 hex chars) | `0xabcdef0123...` | Not supported via CLI (see below) |
+
+**Known limitation:** Hex seed import (`--secret 0x...`) does not work from the command line. The CLI argument parser (`cac`) interprets `0x`-prefixed values as JavaScript numbers, which loses precision for 32-byte seeds. Use a BIP39 mnemonic instead. If you need to import a raw seed programmatically, write it directly to `~/.polkadot/accounts.json`.
+
 ### Query storage
 
 ```bash
@@ -115,6 +123,21 @@ dot tx 0x0503008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48
 dot tx Utility.batchAll '[{"type":"Balances","value":{"type":"transfer_keep_alive","value":{"dest":"5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty","value":1000000000000}}},{"type":"Balances","value":{"type":"transfer_keep_alive","value":{"dest":"5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y","value":2000000000000}}}]' --from alice
 ```
 
+#### Encode call data
+
+Encode a call to hex without signing or submitting. Useful for preparing calls to pass to `Sudo.sudo`, multisig proposals, or governance. Works offline from cached metadata and does not require `--from`.
+
+```bash
+# Encode a remark call
+dot tx System.remark 0xdeadbeef --encode
+
+# Encode a transfer (use the hex output in a batch or sudo call)
+dot tx Balances.transfer_keep_alive 5FHneW46... 1000000000000 --encode
+
+# Use encoded output with Sudo.sudo
+dot tx Sudo.sudo $(dot tx System.remark 0xcafe --encode) --from alice
+```
+
 Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
 ```
@@ -139,6 +162,29 @@ For manual override, use `--ext` with a JSON object:
 dot tx System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"..."}}'
 ```
 
+### Compute hashes
+
+Compute cryptographic hashes commonly used in Substrate. Supports BLAKE2b-256, BLAKE2b-128, Keccak-256, and SHA-256.
+
+```bash
+# Hash hex-encoded data
+dot hash blake2b256 0xdeadbeef
+
+# Hash plain text (UTF-8 encoded)
+dot hash sha256 hello
+
+# Hash file contents
+dot hash keccak256 --file ./data.bin
+
+# Read from stdin
+echo -n "hello" | dot hash sha256 --stdin
+
+# JSON output
+dot hash blake2b256 0xdeadbeef --output json
+```
+
+Run `dot hash` with no arguments to see all available algorithms.
+
 ### Global options
 
 | Flag | Description |
@@ -149,6 +195,21 @@ dot tx System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"...
 | `--output json` | Raw JSON output (default: pretty) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
 
+## How it compares
+
+| | polkadot-cli | @polkadot/api-cli | subxt-cli | Pop CLI |
+|---|---|---|---|---|
+| **Query storage** | SS58 keys, map iteration | yes (full `--ws` URL required) | yes (keys as SCALE tuples, no SS58) | — |
+| **Read constants** | yes | yes | yes | — |
+| **Submit extrinsics** | yes, with dry-run | yes (via `--seed`) | — | ink! contract calls only |
+| **Inspect metadata** | yes | — | yes (excellent browser) | — |
+| **Chain presets** | built-in aliases (`--chain kusama`) | — (manual `--ws` every call) | — | parachain templates |
+| **Tx tracking + explorer links** | spinner progress, block + explorer link | basic events | — | — |
+
+polkadot-cli aims to be the single tool for day-to-day chain interaction: storage reads, constant lookups, transaction submission, and metadata browsing with a polished terminal UX. @polkadot/api-cli covers similar ground but is in maintenance mode and requires verbose flags. subxt-cli has an excellent metadata explorer but cannot sign or submit transactions. Pop CLI targets a different workflow — scaffolding parachains and deploying ink! contracts rather than end-user chain queries.
+
+Outside Polkadot, the closest comparable in terms of interactive UX is [near-cli-rs](https://github.com/near/near-cli-rs) (NEAR).
+
 ## Configuration
 
 Config and metadata caches live in `~/.polkadot/`:
@@ -156,12 +217,14 @@ Config and metadata caches live in `~/.polkadot/`:
 ```
 ~/.polkadot/
 ├── config.json          # chains and default chain
-├── accounts.json        # stored accounts (secrets encrypted at rest — coming soon)
+├── accounts.json        # stored accounts (⚠️ secrets are NOT encrypted — see below)
 └── chains/
     └── polkadot/
         └── metadata.bin # cached SCALE-encoded metadata
 ```
 
+> **Warning:** `accounts.json` stores secrets (mnemonics and seeds) in **plain text**. Encrypted-at-rest storage is planned but not yet implemented. Keep appropriate file permissions (`chmod 600 ~/.polkadot/accounts.json`) and do not use this for high-value mainnet accounts.
+
 ## Development
 
 Requires [Bun](https://bun.sh).