@orangecheck/cli
oc shell tool. OC Attest's check, verify, discover and signed challenges,
plus oc me integrator commands, scriptable, with sensible exit codes.
InstallLink to this section
npm i -g @orangecheck/cli
# or one-shot
npx -y @orangecheck/cli --help
Node 18+.
CommandsLink to this section
oc checkLink to this section
Sybil-gate check against an address.
oc check --addr bc1q... --min-sats 100000 --min-days 30
# ✓ pass
# sats: 125,000
# days: 47
# score: 30.12
Exit code 0 on pass, 2 on fail, 1 on error.
With --json:
oc check --addr bc1q... --min-sats 100000 --min-days 30 --json
# {"ok":true,"sats":125000,"days":47,"score":30.12,"attestation_id":"a3f5b8c2...","identities":[…]}
Also accepts --id <hex> and --identity protocol:identifier.
oc verifyLink to this section
Raw attestation verification against (addr, msg, sig).
oc verify --addr bc1q... --msg "$(cat ./msg.txt)" --sig "AUBH…"
# ✓ valid
# codes: sig_ok_bip322, bond_confirmed
# network: mainnet
# sats: 125,000
# days: 47
# score: 30.12
Exit code 0 when valid, 2 when not, 1 on error. --scheme legacy checks a
BIP-137 signature; the default is bip322.
Or read from a file:
echo '{"addr":"bc1q...","msg":"...","sig":"..."}' | oc verify --file - --json
oc challengeLink to this section
Signed-challenge auth primitive.
# Issue
oc challenge issue --addr bc1q... --audience https://example.com --purpose login
# → the message to sign on stdout; the nonce and expiry on stderr
# with --json: { message, nonce, expiresAt, expiresAtIso }
# --ttl <seconds> sets the lifetime (default 300)
# Verify
oc challenge verify \
--msg "$(cat ./msg.txt)" \
--sig "AUBH..." \
--expected-nonce a3f5b8c2... \
--expected-audience https://example.com \
--expected-purpose login
oc challenge verify also reads { message, signature } as JSON from --file
or stdin, and takes --scheme legacy. Exit code 0 when valid, 2 when not.
oc discoverLink to this section
Query Nostr for attestations.
oc discover --addr bc1q...
# lists all attestations published to the default relay set
oc discover --identity github:alice --json
# { "count": …, "total": …, "attestations": [ …envelopes ] }
Also accepts --id <hex>. --limit <n> caps the list, newest first
(default 50).
oc meLink to this section
Helpers for integrators of ochk.app (API at me.ochk.io).
| Command | What it does |
|---|---|
oc me archetypes | List the archetype templates. |
oc me subtypes | List the billable event subtypes, with what fires each one and a price hint. |
oc me init - | Write a price config from an archetype to oc- (- to change). Archetypes: saas-, marketplace, content-, gaming, agent-. |
oc me validate- | Check a price config file, or stdin. Exit code 1 when it has errors. |
oc me test- | POST one billable event for your own project to https:, to test your webhook handler. Needs your own session token as a bearer token (OC_ or -). It sends no X-, so a project in live mode refuses it. Also takes -, - and -. |
Scripting patternsLink to this section
Shell pipeline — filter a list of addressesLink to this section
while read addr; do
if oc check --addr "$addr" --min-sats 100000 --min-days 30 --json \
| jq -e '.ok' >/dev/null; then
echo "$addr" # passed
fi
done < candidates.txt > allowlist.txt
Cron probe — page on low stakeLink to this section
# /etc/crontab
* * * * * oc check --addr bc1q... --min-sats 10000000 --json \
| jq -e '.ok' >/dev/null \
|| pagerduty-trigger.sh "OC Attest threshold breached"
Global optionsLink to this section
Every command takes --json for machine-readable output and --help for
its options. There are no options for relays, the chain API or the network:
the CLI uses the defaults of @orangecheck/sdk.
Other command-line toolsLink to this section
Each protocol that has a command-line tool ships it as its own package:
| Package | Commands | What it does |
|---|---|---|
@ | stamp, git- | Sign files and git tags with your Bitcoin address, anchor them to Bitcoin, verify offline. See stamp-cli. |
@ | oc- | Verify, inspect and canonicalize OC Agent delegations, actions and revocations. |
@ | oc- | Tally, verify and inspect OC Vote polls. |
@ | oc- | Resolve ocv: secret references and inject them into a process or a config file. |
stamp-cliLink to this section
npm i -g @orangecheck/stamp-cli
Or run it once with npx, in either form. Both run stamp, with the same
output and exit code:
npx -y @orangecheck/stamp-cli verify notes.txt.stamp notes.txt
npx -y -p @orangecheck/stamp-cli stamp verify notes.txt.stamp notes.txt
git-stamp needs the second form: npx -y -p @orangecheck/stamp-cli git-stamp ….
| Command | What it does |
|---|---|
stamp file <path> - | Sign a file and write <path>. beside it; submits to the calendars unless -. |
stamp canonical <path> - | Print the id your wallet signs, without writing anything. |
stamp anchor <stamp> | Submit a stamp to the calendars, or upgrade its pending proof once it is in a block. |
stamp verify <stamp> [content] | Check the signature, the content and the anchor. - fails unless the anchor is confirmed and checked against its block header. |
git- | Stamp <tagname>^{tree} and keep it in .. |
git- | Verify that stamp. |
To sign in a wallet the CLI can't reach, print the id, sign it, and pass the
signature back with the same --signed-at, since the id commits to it:
stamp canonical notes.txt --addr bc1q… --signed-at 2026-10-21T16:00:00Z --id
# sign the printed id with BIP-322 in your wallet, then:
stamp file notes.txt --addr bc1q… --signed-at 2026-10-21T16:00:00Z --sig '<base64 signature>'
stamp verify exits 0 when the stamp checks out, 1 when the file is not a stamp
envelope, and 2 when a check fails (E_BAD_SIG, E_BAD_CONTENT, E_BAD_ANCHOR,
E_NO_ANCHOR). With --require-anchor it exits 3 (ANCHOR_UNCHECKED) when the
block header could not be read: nothing failed, so run it again later. stamp anchor
exits 1 when it cannot reach a calendar or the header source.
From stamp-cli 0.3.2, in the next release, git-stamp verify rebuilds what
git-stamp tag signed, the tag name, its object id and its tree, from the
repository and checks the stamp against that. A tag moved after stamping, or a
.stamp copied from another tag, then fails with exit 2. Earlier versions,
0.3.1 among them, check only the stamp's own signature, not that the tag still
matches it.
--headers-urlLink to this section
stamp verify and stamp anchor take --headers-url <url>: the Esplora API
they read block headers from. The default is https://mempool.space/api. For
each anchor they ask it for two things, GET <url>/block-height/<n> and
GET <url>/block/<hash>/header, so the source learns which blocks you check.
Point it at your own Esplora to keep that to yourself:
stamp verify notes.txt.stamp notes.txt --require-anchor --headers-url https://esplora.example.com/api
| The header source | stamp verify | with - |
|---|---|---|
| answers, and the proof leads to it | confirmed at block N (, exit 0 | the same |
| answers, and the proof does not | E_, exit 2 | the same |
| has no block at that height (404) | E_, exit 2 | the same |
| errors, answers 5xx or is unreachable | claims block N, couldn't check: …, anchor_, exit 0 | ANCHOR_, exit 3 |
stamp anchor needs the header to confirm an upgrade, so with the source
unreachable it stops with OTS upgrade failed, exit 1, and leaves the file as
it was. git-stamp verify has no --headers-url and always reads mempool.space; to use
your own source, run stamp verify .git/stamps/<tagname>.stamp --headers-url ….
See alsoLink to this section
- OC Attest — HTTP API — the same checks as a hosted API
@orangecheck/sdk— programmatic equivalent