paritytech / paritytech/polkadot-cli

feat(query): `--follow` to subscribe to a storage value and print on change

Open
#227 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
10
Forks
2
Avg merge
12h 35m
Merged PRs (30d)
4

Description

Part of #226 (live chain observation). Ship this first — smallest viable streaming slice.

What

Add a `--follow` flag to storage queries so that instead of a one-shot read, the CLI subscribes to the storage item and prints the value each time it changes.

dot polkadot.query.System.Number --follow
dot asset-hub.query.System.Account <addr> --follow

Why

Proves the subscription plumbing with minimal new surface — reuses the existing storage key construction + decode path in `src/commands/query.ts`. No new dashboard/TUI needed. Unblocks the most common "why can't I watch for changes?" need.

Approach

  • Use papi's storage `watchValue` / observable subscription instead of the one-shot read, behind the `--follow` flag (default off = current behavior, no regression).
  • Reuse the existing decode/format path so followed output matches one-shot output.
  • Lifecycle: run until SIGINT (Ctrl-C); tear down the subscription and client cleanly on exit.

Output contract

  • TTY: print each new value (timestamped / labeled) as it arrives.
  • `--json`: newline-delimited JSON, one object per change, drain-safe via `writeStdout`. Depends on #162 (valid JSON for empty values).

Out of scope

  • Multiplexing many keys in one invocation (compose multiple processes for now).
  • The full block/event dashboard — that's `dot watch` (separate child of #226).

Verification

  • `dot .query.System.Number --follow` prints a new number roughly every block.
  • Without `--follow`, behavior is byte-for-byte the existing one-shot output (regression check).
  • `--follow --json | jq` parses cleanly line-by-line.
  • Ctrl-C exits 0 and closes the WS connection (no dangling socket).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/commands/query.ts and trace the existing storage key construction, decode, and format path. Add the --follow flow around papi's watchValue or observable subscription while preserving the one-shot path, then verify regular and --json output, repeated changes, and clean Ctrl-C shutdown with the commands listed in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.