Getting Started

Ritual is a command-line toolkit for Magic: The Gathering. It keeps your decks, collections, and wanted lists as plain markdown files. It prices them, imports from and syncs with the sites you already use, and publishes them as a website you can host anywhere.

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

The installer copies the ritual binary into ~/.local/bin on macOS and Linux (%LOCALAPPDATA%\Programs\ritual\bin on Windows) and adds that directory to your PATH if needed. Open a new shell and run ritual --help to check it worked.

Updating

Once installed, Ritual updates itself: run ritual self-update to install the newest release on your channel, or ritual self-update --check to see whether one exists. A prerelease build keeps following prereleases until you run ritual self-update --stable. Re-running the installer works too. Release builds also print a one-line notice on stderr when a newer release is out.

Prerelease Builds

To try the newest build, prereleases included:

macOS / Linux

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

Windows (PowerShell)

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sloshy/ritual/main/scripts/install.ps1))) -Prerelease

Both installers accept these options:

Option	Environment variable	Description
--prerelease/-Prerelease	RITUAL_PRERELEASE=1	Install the newest release, including prereleases.
--version <tag>/-Version <tag>	RITUAL_VERSION=<tag>	Install a specific release tag. Use prerelease for the newest prerelease.
—	RITUAL_INSTALL_DIR=<dir>	Where to install the binary.

Other Methods

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

./ritual --help

The binaries are not code-signed. A binary downloaded through a browser is therefore blocked on first run: on macOS, Gatekeeper says it cannot be opened (clear the quarantine flag with xattr -d com.apple.quarantine ./ritual); on Windows, SmartScreen warns about an unrecognized app (choose More info, then Run anyway). The install scripts download with curl and Invoke-WebRequest, which do not mark the file, so neither prompt appears.

Each binary is published with a .sha256 checksum and a build provenance attestation. To confirm a download came from Ritual’s release workflow, run gh attestation verify ./ritual --repo sloshy/ritual with the GitHub CLI.

Building from Source

Ritual runs on Bun. Install the dependencies, then build the binary:

bun install
bun run build

Your First Deck

Ritual works in the directory you run it from. Make a folder for your cards, step into it, and create a deck:

ritual new deck "My Commander Deck"    # add --format modern (or standard, …) for other formats
ritual add-card "My Commander Deck" Sol Ring

The first command that needs card data offers to download Scryfall’s card database into a local cache. Say yes. Later commands read from that cache, so they are fast and work offline.

Already have a deck online? Import it from Archidekt, Moxfield, or MTGGoldfish instead:

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

From here:

ritual edit                       # open the interactive editor
ritual price "My Commander Deck"  # what the deck costs today
ritual serve --build              # build the website and serve it at http://localhost:3000

What You Get

• Lists as files. Each deck, collection, and wanted list is one markdown file under decks/, collections/, or wanted/. Edit them with Ritual or by hand. See List Files.
• Three ways to work. The command line, a browser-based admin site you run with ritual admin, and a public site you build and host.
• Imports and syncs. Decks from Archidekt, Moxfield, MTGGoldfish, plain text, and CSV files, plus two-way sync with Archidekt for decks and your collection.
• Prices. TCGplayer, Cardmarket, Card Kingdom, and Cardhoarder (MTGO tix) prices for every list, and Card Kingdom buylist quotes when you want to sell.
• Card lookup. Search Scryfall with its full query syntax from the terminal.
• AI agents. An MCP server and installable agent skills so an assistant can drive Ritual for you.

Where to Go Next

• List Files explains the file format Ritual reads and writes.
• Configuration covers the optional ritual.config.json.
• CLI Conventions lists the global options, scripting output, and exit codes shared by every command.
• Commands is the full command reference.
• Public Site and Admin Site describe the two web interfaces.