CLI

Run it

pnpm add -g @agntn/puzzles
puzzles stats

Total: 332
Solved: 130
Unsolved: 93
Claimed: 11
Swept: 96
Expired: 2
With pubkey: 236

Examples

puzzles list b1000 --status unsolved              # 77 lines, id, status, prize, address
puzzles list --with-pubkey --json | jq -r '.[].id' # every puzzle with a known public key
puzzles show hash_collision/sha256 --json          # the record, redeem script included
puzzles verify b1000/135                           # OK b1000/135
puzzles export --compact > puzzles.json            # a snapshot with its data_version
puzzles stats --json | jq .unsolved_prize          # { "BTC": 907.88…, "ETH": 1, "AR": 1900 }

The line format of show and list is tab separated: b1000/71 unsolved 7.100226 BTC 1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU. A puzzle without a recorded prize prints - in the third column. Statuses for --status are unsolved, solved, claimed, swept and expired. Anything else is an error, not an empty list.

Exit codes

show, verify, balance and a list with an unknown collection print a message and exit 1. verify --all exits 1 when any puzzle with a key derives the wrong address. Puzzles without a key don't count, which is what a CI gate wants. list with a status that matches nothing prints nothing and exits 0. Don't use an empty list as a check.

puzzles verify --all --quiet && echo "every published key derives its address"

A closed pipe ends the process quietly: puzzles export | head doesn't crash with an EPIPE trace. And --help doesn't load the MCP SDK. The mcp command imports it when it runs, so listing the commands costs a few milliseconds.

Machine output

--json goes through one serializer. It prints bigint as a string and leaves absent fields out. Nothing on the CLI prints data through a logger. consola silences its output under NODE_ENV=test, and a script that parses an empty string fails far from the cause.