Skip to content
On this page

@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

Shell
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.

Shell
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:

Shell
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).

Shell
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:

Shell
echo '{"addr":"bc1q...","msg":"...","sig":"..."}' | oc verify --file - --json

oc challengeLink to this section

Signed-challenge auth primitive.

Shell
# 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.

Shell
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).

CommandWhat it does
oc me archetypesList the archetype templates.
oc me subtypesList the billable event subtypes, with what fires each one and a price hint.
oc me init --archetype <id> --project-key <pk> --domain <domain> --name <name>Write a price config from an archetype to oc-config.json (--out <path> to change). Archetypes: saas-paywall, marketplace, content-platform, gaming, agent-only.
oc me validate-config [file]Check a price config file, or stdin. Exit code 1 when it has errors.
oc me test-fire <project_key> <subtype>POST one billable event for your own project to https://me.ochk.io/api/integrator/event, to test your webhook handler. Needs your own session token as a bearer token (OC_BEARER_TOKEN or --token). It sends no X-OC-Signature, so a project in live mode refuses it. Also takes --action-label, --payment-amount-sats and --origin.

Scripting patternsLink to this section

Shell pipeline — filter a list of addressesLink to this section

Shell
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

Shell
# /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:

PackageCommandsWhat it does
@orangecheck/stamp-clistamp, git-stampSign files and git tags with your Bitcoin address, anchor them to Bitcoin, verify offline. See stamp-cli.
@orangecheck/agent-clioc-agentVerify, inspect and canonicalize OC Agent delegations, actions and revocations.
@orangecheck/vote-clioc-voteTally, verify and inspect OC Vote polls.
@orangecheck/vault-clioc-vaultResolve ocv:// secret references and inject them into a process or a config file.

stamp-cliLink to this section

Shell
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:

Shell
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 ….

CommandWhat it does
stamp file <path> --addr <address>Sign a file and write <path>.stamp beside it; submits to the calendars unless --no-anchor.
stamp canonical <path> --addr <a> --idPrint 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. --require-anchor fails unless the anchor is confirmed and checked against its block header.
git-stamp tag <tagname>Stamp <tagname>^{tree} and keep it in .git/stamps/<tagname>.stamp.
git-stamp verify <tagname>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:

Shell
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:

Shell
stamp verify notes.txt.stamp notes.txt --require-anchor --headers-url https://esplora.example.com/api
The header sourcestamp verifywith --require-anchor
answers, and the proof leads to itconfirmed at block N (checked against the block header), exit 0the same
answers, and the proof does notE_BAD_ANCHOR, exit 2the same
has no block at that height (404)E_BAD_ANCHOR, exit 2the same
errors, answers 5xx or is unreachableclaims block N, couldn't check: …, anchor_state: unchecked, exit 0ANCHOR_UNCHECKED, 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