CLI review: improvement roadmap

CLI Review: Improvement Roadmap

A comprehensive review of the CLI's architecture, ergonomics, and scripting capabilities — based on analyzing the codebase, setup-pusd.sh, and dimflow.md.

---

What's Working Well

The CLI is well-architected and genuinely useful:

• Metadata-driven type parsing is the crown jewel — auto-coerces primitives, unwraps XCM single-element arrays, auto-wraps MultiAddress, all from metadata
• Dev accounts as first-class citizens eliminate the most common friction in testnet workflows
• --encode for nested calls (the Sudo pattern) is elegant — compose calls via shell substitution
• Offline metadata caching means most operations are instant after first use
• Progressive tx tracking (Signing → Broadcasted → Best block → Finalized) is excellent UX
• Fuzzy suggestions on typos via Levenshtein is a nice touch
• Non-zero exit on dispatch error makes the CLI script-safe

Value Over polkadot-api Directly

Task	polkadot-api (TS)	polkadot-cli
Setup boilerplate	~20 lines	0
Dev account signing	~10 lines	--from alice
Simple transfer	~8 lines	1 command
Nested Sudo call	~15 lines	dot tx Sudo.sudo $(dot tx ... --encode)

Where the gap narrows: Complex multi-step workflows still require similar ceremony in bash vs TypeScript. The JSON authoring pain is the main bottleneck.

---

Improvement Roadmap

Phase 1 — Quick Wins (low effort, high impact)

Issue	Description
#21	Human-readable amounts — parse "100 DOT" and _ separators in numeric args
#22	Type-aware query key parsing — use metadata types for dot query keys instead of generic parseValue()
#23	Offline constant lookups — read constants from cached metadata without live connection
#24	Fix 0x hex seed import — add --secret-file / --secret-stdin to bypass CAC parser limitation

Phase 2 — Developer Experience

Issue	Description
#9	Inline call-type parameter syntax — Sudo, Utility.batch, Proxy wrappers
#25	Refactor tx.ts — split 850-line file into tx-parse, tx-submit, tx-display modules
#26	Address book / contacts — named recipient addresses (dot address add treasury 5FHn...)
#27	Shell completions — generate zsh/bash completions from cached metadata
#20	Shorthand aliases — for chains and accounts

Phase 3 — Scripting & Piping

Issue	Description
#6	Structured exit codes — pipe-friendly output for scripted workflows
#4	--wait polling flag — for dot query subscriptions
#5	--batch — submit multiple transactions
#3	--file flag — binary data in dot tx

Phase 4 — XCM & Advanced

Issue	Description
#13	XCM file format — RFC for authoring cross-chain programs
#12	Replace --encode with encode command

Future Considerations (not yet tracked)

These ideas came up during review but are larger efforts that may warrant separate RFCs:

• Script/recipe runner — declarative YAML for multi-step workflows (replaces bash scripts like setup-pusd.sh)
• --verbose/--quiet flags — control output verbosity
• Interactive REPL mode — stay connected to a chain for exploration
• --output raw and --output json --field — jq-less value extraction

---

How This Improves Real Workflows

setup-pusd.sh (160-line stablecoin setup script)

Improvement	Impact
#13 XCM helpers	Cuts JSON authoring in half
#21 Human-readable amounts	Self-documenting values
#26 Address book	Eliminates hardcoded pubkeys

dimflow.md (300-line cross-chain runbook)

Improvement	Impact
#4 --wait	Replaces manual polling loops
#6 Structured exit codes	Machine-parseable results
#21 Human-readable amounts	Clearer step descriptions

---

Sub-Issues

New:

• #21 — Human-readable amounts
• #22 — Type-aware query key parsing
• #23 — Offline constant lookups
• #24 — Fix 0x hex seed import
• #25 — Refactor tx.ts
• #26 — Address book / contacts
• #27 — Shell completions

Existing:

• #3 — --file flag for binary data
• #4 — --wait polling flag
• #5 — --batch for multiple transactions
• #6 — Structured exit codes
• #7 — Transaction history and replay
• #9 — Inline call-type parameter syntax
• #12 — Replace --encode with encode command
• #13 — XCM file format RFC
• #20 — Shorthand aliases for chains and accounts

Start by reading setup-pusd.sh and dimflow.md, then review the listed sub-issues and their descriptions. This issue is complete when the broad roadmap has been turned into individually scoped, actionable work items with clear acceptance criteria; it does not identify a single implementation file or test.