Getting Started

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

Installation

macOS / Linux

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

Windows (PowerShell)

irm https://raw.githubusercontent.com/sloshy/ritual/main/scripts/install.ps1 | iex

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:

Option	Description
--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. The directory locations themselves can be customized via ritual.config.json — paths in that file are interpreted relative to --base-dir.

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.