# Command line

The official `raritydb` CLI covers the whole API from your terminal: cards, sets, species, prices, sealed products, pull rates and your account. Every command runs one GraphQL query. Add `--json` to any command for the raw data, which is handy in scripts and for agents that drive a shell.

## Install

Requires Node 18 or newer. Until the CLI is published to npm (as `npm install -g raritydb`), install it from the repository:

```bash
cd cli && npm install && npm run build && npm link
```

## Sign in

```bash
raritydb login
```

`login` shows a short code and opens your browser; on a machine without one (SSH), use `raritydb login --no-browser` and open the printed link anywhere. Sign in to RarityDB if you're asked to, check that the code matches, and press **Approve**. The CLI then receives its own API key, named "CLI on <your computer>", and saves it to `~/.raritydb/config.json`, readable only by you. `raritydb logout` revokes that key and forgets it.

Other ways to sign in:

- **Existing key:** `raritydb login --key rdb_…` saves a key you already have.
- **Environment:** set `RARITYDB_API_KEY` (and `RARITYDB_URL` for another server).
- **Per command:** use `--api-key` and `--base-url`. Flags beat the environment, which beats the saved file.

## Commands

| Command | What it does |
|---|---|
| `raritydb whoami` | Your account, plan and today's usage |
| `raritydb search <text>` | Fuzzy search across species, sets and cards |
| `raritydb card <code>` | One card: attacks, species, printings, prices, IDs elsewhere. Also `--tcgplayer <id>` or `--cardmarket <id>` |
| `raritydb cards [filters]` | Cards by `--name --set --dex --rarity --type --illustrator --supertype --region --standard --physical`, paged with `--first` / `--after` |
| `raritydb set <code>` / `raritydb sets` | A set and its cards, or the list of sets (`--region --series --physical`) |
| `raritydb species <dex or slug>` | A Pokémon with forms, evolution line and cards (`--cameos`) |
| `raritydb resolve <source> <ids…>` | Translate tcgdex / pokemontcg.io / tcgplayer / cardmarket IDs |
| `raritydb prices <code>` | Cardmarket prices per printing, in US dollars (converted from euros at the ECB rate; `--currency EUR` for the originals, or GBP, CAD, AUD, JPY). `--history <days>`, `--links` for USD marketplaces, and `--provider <name> --provider-key <key>` for live USD and graded prices with your own key |
| `raritydb sealed` | Sealed products (`--set --kind --name --region`). `--contents` shows what's inside, `--ev` the expected value |
| `raritydb pull-rates <set>` | Pull rates with their source study and EV per pack. `--sealed <kind>` adds that set's sealed products. `card`, `prices`, `sealed` and `pull-rates` all take `--currency` (default USD) |
| `raritydb identify <photo>` | Identify a card and its exact printing from a photo file or https URL. `--tilted <photo>` adds a tilted shot to tell holo from reverse holo. See [Identify a card from a photo](/docs/identify) |
| `raritydb identify-cards <photo>` | Every card in a photo of several, a spread or a binder page. `--grid 3x3` splits a page whose cards touch. Each card counts as one photo check |
| `raritydb slab <grader> <cert>` | Where to verify a slab's cert, and a warning if the number can't be that grader's. `identify` prints this for slabs too |
| `raritydb condition <front>` | Condition from photos: centering, whitening, damage and a grade range. `--back <photo>` narrows the range. See [Card condition from photos](/docs/condition) |
| `raritydb fake-check <front>` | Red flags that a card is fake. `--back <photo>` is strongly recommended. See [Fake check](/docs/authenticity) |
| `raritydb webhooks add\|list\|test\|rotate\|rm` | Webhook endpoints for price alerts. `add` prints the signing secret once |
| `raritydb alerts add <card> --above\|--below\|--change <n> --webhook <id>` | A price alert on a printing's Cardmarket trend (`--printing <key>` when there are several). `alerts list`, `alerts rm <id>` |
| `raritydb pullbook buy\|pulls\|purchases\|purchase\|open\|item\|extra-cost\|inventory\|holdings\|settings\|rm` | Your Pullbook seller ledger: log purchases (`--cost-unknown` for cards you've had for years), add pulls, see inventory at cost and holdings at market value. See [Pullbook](/docs/pullbook) |
| `raritydb pullbook sell\|sales\|sale\|review\|resolve\|events\|event-add\|rm-sale\|rm-event` | Record sales (fees from the channel's schedule), settle lines waiting for a match, streams and shows |
| `raritydb pullbook report\|tax` | What you made by purchase, stream or show, product or month; a year's sales for taxes (`--csv`) |
| `raritydb pullbook import\|import-finish\|imports` | Import a Whatnot, eBay, TCGplayer or other sales export (CSV); `--map field=Column` for other layouts |
| `raritydb query '<graphql>'` | Any GraphQL query (`--variables '{…}'`, `--file q.graphql`). Prints JSON |
| `raritydb docs [guide]` | These docs, in your terminal |
| `raritydb schema` | The GraphQL schema |

## Examples

```bash
raritydb card sv03.5-006
raritydb cards --dex 25 --region INTERNATIONAL --first 50 --json | jq '.nodes[].code'
raritydb resolve pokemontcg.io base1-4 sv3pt5-6
raritydb sealed --set me02 --kind etb --contents --ev
raritydb prices sv03.5-006 --provider pokemonpricetracker --provider-key "$PPT_KEY"
```

If a command fails you get a one-line message and exit code 1: not signed in, key revoked, rate limited (with the wait time), or a GraphQL error.