scry

Run a Scryfall card search with Scryfall’s own query syntax, or fetch random cards with --random.

Usage

ritual scry <query> [options]
ritual scry [query] --random [options]

Arguments

Argument	Description	Required
[query]	Scryfall search query (with --random, filters the picks)	Unless --random is given

Options

Option	Description	Default
--pages <number>	Fetch up to this many pages, without prompting	1 when interactive paging is unavailable
--random	Fetch random cards instead of searching	false
--count <number>	Number of random cards to fetch (--random only)	1
--fields <list>	Comma-separated fields for json/ndjson output	-
--output <format>	Output format (json, ndjson, text, or csv)	json

Rules:

• Without --random, a search query is required.
• --random cannot be combined with --pages or --output csv, and --count requires --random. Either combination is a usage error.
• --pages and --count must be positive integers within their caps (20 and 50). Any other value is a usage error.
• --output csv is an extra format for the same payload, rendered by Scryfall server-side.
• There is no --quiet: the results are the payload, and the truncation notice below warns about lost content, so the convention lets --quiet hide neither. Everything else follows the shared scripting conventions.

Paging

Scryfall returns search results in pages. How many scry fetches:

• --pages <n> fetches up to n pages and never prompts, in a terminal or not.
• Without --pages, in an interactive terminal (stdout and stdin are both TTYs and prompting is allowed), scry asks “Fetch next page?” after each page until you decline or the results run out.
• Everywhere else (piped output, scripts, or the global --no-input flag / RITUAL_NO_INPUT environment variable), exactly one page is fetched.

When a non-interactive run stops with results still available, one line goes to stderr in every output mode: Fetched 175 of 4210 results (page 1); use --pages <n> for more. (with CSV output, More results remain (fetched page 1); use --pages <n> for more.). It prints so a capped run is never mistaken for a complete one.

A run fetches at most 20 pages. Each page is a separate, paced Scryfall request, so the cap protects their API as well as guarding against a mistyped --pages. A larger value is rejected at parse time with a message naming the cap. --count is capped at 50 for the same reason.

Note

Use the global --no-input flag to guarantee no prompting, and --pages <n> to fetch a fixed number of pages. There is no fetch-all flag.

Output across pages

A scripted --output json run (the default) always emits one JSON array of cards, whether it walked one page or five and whether it found matches or none. The pages are collected and written once at the end. A run that fails partway still emits the cards that arrived, and a run that found nothing emits [] (with the error on stderr and a non-zero exit code).

Interactive paging is the exception: those runs print each page as it arrives, so you can see it before asking for the next.

--output ndjson streams one document per card as each page arrives. --output text prints one Name (SET) line per card as each page arrives. --output csv concatenates the pages’ rows, writing the header once.

Random Cards

--random fetches random cards instead of running a search. The query, when given, filters the selection: each pick is a random card matching it. Cards are fetched one request at a time (Scryfall rate limiting applies), so large --count values take proportionally longer.

A single pick (--count 1, the default) emits a bare card object. --count greater than 1 emits an array (one line per card with --output ndjson). --output text prints one Name (SET) line per card. --fields works as with searches. If any fetch fails or a pick comes back empty, nothing is printed and the command exits non-zero.

Get a completely random card:

ritual scry --random

Get a random legendary creature:

ritual scry "type:legendary type:creature" --random

Get five random cards under $1:

ritual scry "usd<1" --random --count 5

Get text output for shell scripts:

ritual scry --random --output text

Examples

Search for legendary creatures:

ritual scry "type:legendary type:creature"

Search for cards legal in Commander under $5:

ritual scry "legal:commander usd<5"

Export search results to CSV:

ritual scry "set:mh2 type:creature" --output csv > creatures.csv

Force text output:

ritual scry "type:artifact" --output text

Stream projected card fields as NDJSON:

ritual scry "type:artifact" --fields name,set,prices.usd --output ndjson

Get multiple pages of results without prompts:

ritual scry "type:planeswalker" --pages 5

Query Syntax

This command uses Scryfall’s search syntax. Some common operators:

Operator	Example	Description
type:	type:creature	Filter by card type
set:	set:mh2	Filter by set code
cmc:	cmc:3	Filter by mana value
c:	c:blue	Filter by color
legal:	legal:commander	Filter by format legality
usd<	usd<10	Filter by price

Exit Codes

Code	Meaning
0	Results printed
1	Request failure while fetching a page or a random card
2	Usage error (missing query without --random, --random with --pages or --output csv, --count without --random, --fields with --output csv or text output)
3	No search results found, or no card matched the random filter