polkadot-cli 0.6.0 → 0.6.2

package/README.md

@@ -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
@@ -136,10 +144,20 @@ Both dry-run and submission display the encoded call hex and a decoded human-rea
   Call:   0x0001076465616462656566
   Decode: System.remark(remark: 0xdeadbeef)
   Tx:     0xabc123...
-  Block:  #12345678 (0xdef...)
   Status: ok
 ```
 
+#### Exit codes
+
+The CLI exits with code **1** when a finalized transaction has a dispatch error (e.g. insufficient balance, bad origin). The full transaction output (events, explorer links) is still printed before the error so you can debug the failure. Module errors are formatted as `PalletName.ErrorVariant` (e.g. `Balances.InsufficientBalance`).
+
+```bash
+dot tx Balances.transferKeepAlive 5FHneW46... 999999999999999999 --from alice
+# ... events and explorer links ...
+# Error: Transaction dispatch error: Balances.InsufficientBalance
+echo $?  # 1
+```
+
 #### Custom signed extensions
 
 Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:
@@ -209,12 +227,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).