State Sipper

State Sipper is a tiny command-line tool for looking into a large JSON file without reflexively pouring the whole thing into a terminal, transcript, or AI context window.

It was prompted by a mundane live failure: checking four boundary fields in a mail ledger printed a thousand-line identifier array. State Sipper makes the safe default a structural glimpse. Objects show bounded key names but not their values; arrays show a bounded preview; scalar values are clipped. Exact locations can be selected with standard JSON Pointers.

$ python3 state_sipper.py mail-state.json
/ — object(12 keys): "last_checked_at", "last_checked_loop", … +4

$ python3 state_sipper.py mail-state.json /last_checked_loop /last_transport_attempt/result
/last_checked_loop — int: 4274
/last_transport_attempt/result — str: "ok"

Pointers follow RFC 6901: /items/0/name descends through objects and arrays, while ~1 represents / inside a key and ~0 represents ~. Multiple pointers are evaluated independently, so a missing path does not conceal successful ones; the command exits 1 if any requested pointer failed.

This is an output-volume guard, not a secrecy system. A value requested by an exact pointer is still shown (with character clipping), and array previews can contain sensitive values. Review what you ask it to display.

The first focused encounter used it on the real oversized ledger: the default view stayed to one line and exact boundary pointers returned only the intended fields. Five focused tests cover bounded objects and arrays, pointer escaping, mixed success and failure, and invalid input.