Skip to main content

Getting Started

An all-in-one toolkit for Magic: The Gathering decks, collections, and self-hosting.

Installation​

curl -fsSL https://raw.githubusercontent.com/sloshy/ritual/main/scripts/install.sh | bash

Other Methods​

You can also download a platform-specific binary from the releases page and run it directly:

./ritual --help

Building from Source​

This project uses Bun as its runtime. First, install dependencies:

bun install

Then build the binary:

bun run build

Quick Start​

Create Your First Deck​

./ritual new-deck "My Commander Deck" --format commander

Import a Deck from a Website​

Import decks from Archidekt, Moxfield, or MTGGoldfish:

./ritual import https://archidekt.com/decks/12345

Get Pricing Information​

./ritual price "My Commander Deck"

Generate a Static Website (Experimental)​

Ritual supports building static websites to showcase your decks (and soon, your collection). This is an experimental feature, so expect some rough edges. To build and serve the site locally:

./ritual build-site
./ritual serve

Then open http://localhost:3000 to view your deck collection.

Global Options​

These options are available on every command:

OptionDescription
--base-dir <path>Use this directory instead of the current working directory
--cache-server <host:port>Use a remote cache server instead of local cache files

--base-dir​

By default, Ritual reads and writes files relative to the directory you run it from (the current working directory). Use --base-dir to point Ritual at a different directory without needing to cd there first:

# Run from anywhere, but operate on files in ~/my-collection
ritual --base-dir ~/my-collection build-site

# Price all decks in a specific project directory
ritual --base-dir /projects/mtg price "My Deck"

This affects all file paths: decks, collections, wanted lists, cache, config files, and the output dist/ directory.

Features​

  • Deck Management: Create and organize your MTG decks
  • Multi-source Import: Import from Archidekt, Moxfield, MTGGoldfish, or local files
  • Scryfall Integration: Full card search powered by Scryfall
  • Pricing: Get min, max, and latest prices for your decks
  • Static Site Generation: Create a self-hosted website to showcase your decks or collection
  • Caching: Smart caching for fast card lookups

Scripting quickstart​

Use structured output for automation:

./ritual price "My Commander Deck" --output json | jq '.totals'

Stream multiple card lookups as NDJSON:

./ritual card --from-file cards.txt --output ndjson --fields name,set,prices.usd

Avoid interactive prompts in CI:

./ritual import-account johndoe --all --non-interactive --dry-run

Migration notes​

  • Prefer --output json or --output ndjson for script parsing.
  • Use --fields to project stable subsets of data.
  • Add --non-interactive (and --yes when needed) in headless environments.