Created by @veltri-23 (Hunter Veltri).
Contributors: @cathrynlavery (Cathryn Lavery).
Quick Start
1. Install
See Install above.
2. Verify Setup
scryfall-pp-cli doctor
This checks your configuration.
3. Try Your First Command
scryfall-pp-cli cards search --q example-value
Usage
Run scryfall-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data such as data.db |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
SCRYFALL_CONFIG_DIR, SCRYFALL_DATA_DIR, SCRYFALL_STATE_DIR, or SCRYFALL_CACHE_DIR
--home <dir> for this invocationSCRYFALL_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export SCRYFALL_HOME=/srv/scryfall
scryfall-pp-cli doctor
Under SCRYFALL_HOME=/srv/scryfall, the four dirs resolve to /srv/scryfall/config, /srv/scryfall/data, /srv/scryfall/state, and /srv/scryfall/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"scryfall": {
"command": "scryfall-pp-mcp",
"env": {
"SCRYFALL_HOME": "/srv/scryfall"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as SCRYFALL_DATA_DIR overrides an explicit --home for that kind. Use SCRYFALL_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting SCRYFALL_HOME does not move files back to platform defaults, and doctor cannot find files left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. Run scryfall-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
bulk-data
Manage bulk data
scryfall-pp-cli bulk-data - Returns a List of all bulk data items on Scryfall.
cards
Manage cards
scryfall-pp-cli cards autocomplete - Autocompletescryfall-pp-cli cards get-all - Returns a List object that contains all cards in Scryfall’s database. This method is paginated, returning 175 cards at a time. The cards are ordered roughly newest to oldest.scryfall-pp-cli cards get-by-arena-id - Get by arena idscryfall-pp-cli cards get-by-cardmarket-id - Fetch a card by its Cardmarket IDscryfall-pp-cli cards get-by-code-by-number - Get by code by numberscryfall-pp-cli cards get-by-id - Get by idscryfall-pp-cli cards get-by-mtgo-id - Get by mtgo idscryfall-pp-cli cards get-by-multiverse-id - Get by multiverse idscryfall-pp-cli cards get-by-tcgplayer-id - Fetch a card by its TCGplayer IDscryfall-pp-cli cards get-named - Get namedscryfall-pp-cli cards get-random - Get randomscryfall-pp-cli cards post-collection - Accepts a JSON body with an identifiers array (max 75). Supported identifier keys: id, mtgo_id, arena_id, multiverse_id, name, set + collector_number, collector_number.scryfall-pp-cli cards rulings-get-by-mtgo-id - Rulings get by mtgo idscryfall-pp-cli cards rulings-get-by-multiverse-id - Rulings get by multiverse idscryfall-pp-cli cards search - Returns a List object containing Cards found using a fulltext search string. This string supports the same fulltext search system that the main site uses.
catalog
Manage catalog
scryfall-pp-cli catalog get-artifact-types - Get artifact typesscryfall-pp-cli catalog get-card-names - Get card namesscryfall-pp-cli catalog get-creature-types - Get creature typesscryfall-pp-cli catalog get-enchantment-types - Get enchantment typesscryfall-pp-cli catalog get-land-types - Get land typesscryfall-pp-cli catalog get-loyalties - Get loyaltiesscryfall-pp-cli catalog get-planeswalker-types - Get planeswalker typesscryfall-pp-cli catalog get-powers - Get powersscryfall-pp-cli catalog get-spell-types - Get spell typesscryfall-pp-cli catalog get-toughnesses - Get toughnessesscryfall-pp-cli catalog get-watermarks - Get watermarksscryfall-pp-cli catalog get-word-bank - Get word bank
sets
Manage sets
scryfall-pp-cli sets get-all - Returns a List object of all Sets on Scryfallscryfall-pp-cli sets get-by-code - Returns a Set with the given set code. The code can be either the code or the mtgo_code for the set.scryfall-pp-cli sets get-by-id - Returns a Set with the given Scryfall id.scryfall-pp-cli sets get-by-tcgplayer-id - Returns a Set with the given tcgplayer_id, also known as the groupId on TCGplayer’s API.
symbology
Manage symbology
scryfall-pp-cli symbology get-all - Get allscryfall-pp-cli symbology parse-mana - Parse mana
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
scryfall-pp-cli recall <query> - Look up cached resources for a query before running discoveryscryfall-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)scryfall-pp-cli learnings list - Inspect taught rowsscryfall-pp-cli learnings forget <query> - Undo a teachscryfall-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectscryfall-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsscryfall-pp-cli teach-pattern - Install a query/resource template up frontscryfall-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set SCRYFALL_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of scryfall-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
scryfall-pp-cli cards search --q example-value
# JSON for scripting and agents
scryfall-pp-cli cards search --q example-value --json
# Filter to specific fields
scryfall-pp-cli cards search --q example-value --json --select id,name,status
# Dry run — show the request without sending
scryfall-pp-cli cards search --q example-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
scryfall-pp-cli cards search --q example-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - synced data supports local browsing and the CLI's local search command
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Scryfall's cards search, cards autocomplete, and cards get-random need the live API. The local mirror cannot reproduce their results accurately, so they return an error when only local data is available. Exact card names, supported alternate card IDs, and set codes can resolve from synced data. Image/text formats and card face/version options also need the live API.
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited, 10 config error.
Health Check
scryfall-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run scryfall-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/scryfall-pp-cli/config.toml; --home, SCRYFALL_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
TLS certificates are verified by default. For a trusted development or self-signed endpoint only, pass --insecure for one invocation, set SCRYFALL_SKIP_TLS_VERIFY=true for the current environment, or set skip_tls_verify = true in the config file for a persistent override.
Generated by CLI Printing Press