init-site

Initialize the current directory for publishing a Ritual site.

Usage

ritual init-site [options]

Option	Description
`-u, --upgrade`	Upgrade tracked workflows to the current version without prompting
`-f, --force`	Re-initialize and overwrite all generated files, ignoring the existing site config
`--ci <system>`	CI system for a fresh init: `github-actions` or `manual`
`--deploy <mode>`	Deploy mode: `publish-for-me` or `local-build` (github-actions only)
`--dist-dir <dir>`	Directory containing your locally built site (local-build deploys only)
`--change-detection` / `--no-change-detection`	Enable or disable automatic change detection (publish-for-me only — either form is a usage error with `--ci manual` or `--deploy local-build`)
`--currency <currency>`	Default price currency: `usd`, `eur`, or `tix`
`--overwrite-readme` / `--no-overwrite-readme`	Overwrite or keep an existing `README.md` without prompting
`--skills`	Install Ritual agent skills into `.claude/skills` without prompting
`--no-skills`	Skip installing Ritual agent skills (no prompt)

This command creates the scaffolding files needed to publish a Ritual-built deck and collection site. It prompts you to choose a CI system, then a deployment strategy, then the default price currency (usd, eur, or tix — defaulting to USD, stored as the root-level defaultCurrency key), and generates the appropriate files.

Every fresh-init prompt has a matching flag (listed with each prompt below). A value provided by a flag skips its prompt; invalid values are rejected at parse time. Flags that do not apply to the chosen CI system or deploy mode are usage errors (e.g. --deploy with --ci manual, or --dist-dir with --deploy publish-for-me).

The site settings are stored under the site key of ritual.config.json. On subsequent runs, init-site compares the current Ritual version to the version recorded there. If a newer version is detected, it prompts you to confirm before regenerating any tracked managed files. The fresh-init flags above only apply to a fresh init (or --force); passing them on an already-initialized repository is a usage error.

Headless Runs

When prompts are unavailable (--no-input / RITUAL_NO_INPUT, or stdin is not a terminal), any prompt whose flag was not provided is a usage error (exit 2) naming the missing flag. A fully-flagged headless init looks like:

ritual init-site \
  --ci github-actions \
  --deploy publish-for-me \
  --change-detection \
  --currency usd \
  --no-skills

The same applies to overwrite decisions: an existing README.md needs --overwrite-readme, --no-overwrite-readme, or --force; an existing generated workflow needs --force; and a pending version upgrade needs --upgrade.

Prompts

CI system

Flag: --ci <system>

? Which CI system are you using?
❯ GitHub Actions — Generate a GitHub Actions workflow that builds and deploys automatically
  Manual / None — No CI integration — build and deploy manually

GitHub Actions (--ci github-actions) generates a workflow file in .github/workflows/ to automate your deployments.

Manual / None (--ci manual) skips any CI file generation. You build and deploy the site yourself.

Deploy mode (GitHub Actions only)

Flag: --deploy <mode>

? How would you like to deploy your site?
❯ Publish for me — Generate a GitHub Action that builds your site and deploys it automatically
  Deploy my local build — Generate a GitHub Action that deploys a directory you build locally with build-site

Publish for me (--deploy publish-for-me) generates a GitHub Action that:

Resolves the Ritual version (or uses the pinned RITUAL_VERSION variable) and restores the Ritual binary from cache if the version hasn’t changed
Downloads the Ritual binary only when the resolved version is not already cached
Restores the Scryfall card cache from a previous run (using GitHub Actions caching)
Runs ritual build-site --refresh auto to build your site
Deploys the dist/ directory to GitHub Pages

Deploy my local build (--deploy local-build) generates a simpler action that deploys a pre-built directory you commit to the repository. Because that directory is committed, it is not gitignored: the generated .gitignore omits it and appends an explicit !<distDir>/ un-ignore (so a dist/ line an earlier init wrote stops covering it), and the generated README tells you to commit it. If some other pattern in your .gitignore still covers the directory — a wildcard the un-ignore cannot undo, such as di*, dist/* or dist/** — init-site names the offending lines so you can remove or narrow them, rather than leaving you to discover an empty deploy.

Build directory (local build only)

Flag: --dist-dir <dir>

If you choose “Deploy my local build”, you’ll be asked which directory contains the built site:

? Which directory contains your built site? (dist)

The default is dist, which is where build-site writes its output. Any other directory needs --out-dir, so every generated instruction renders the flag: the README, the “next steps” summary, and the preview command all read ritual build-site --out-dir <dir> / ritual serve --build --out-dir <dir>.

Automatic change detection (publish for me only)

Flags: --change-detection / --no-change-detection

If you choose “Publish for me”, you’ll be asked whether to enable automatic change detection:

? Enable automatic change detection? (commits changelogs when list files change) (y/N)

When enabled, the generated workflow runs detect-changes before building the site, diffing against github.event.before (falling back to HEAD~1 when that is empty or the all-zeros SHA, as on the first push to a branch). If any deck, collection, or wanted list files were modified in the push, it generates changelog entries and commits them automatically. The site build is skipped for that run since the new commit will trigger a fresh build with the updated changelogs. If detect-changes itself exited nonzero, the step commits and pushes first and then fails, so a partial run never strands the changelogs it did write.

This is useful when you edit list files directly (outside the admin UI or CLI) and want changelogs to stay up to date without manual intervention.

Detection is hash-aware, so it’s safe to leave enabled even if you also edit with Ritual locally: files whose contents still match their .sha256 sidecar (i.e. Ritual itself wrote them and already recorded a changelog) are skipped, and only hand-edited files are processed. See Hash-aware detection for details.

Default currency

Flag: --currency <currency>

? Default price currency?
❯   USD (current) - US Dollars (TCGplayer)
    EUR - Euros (Cardmarket)
    TIX - MTGO tickets

Sets the root-level defaultCurrency key — the currency the price command, editor price displays, and the public site default to. USD is the default; the currently configured value is preselected. Change it later with config set defaultCurrency <usd|eur|tix>.

Agent skills

After the site files are written, init-site offers to install the Ritual agent skills:

? Install Ritual agent skills into .claude/skills so coding agents can work with this repository? (Y/n)

If you keep your decks, collections, and wanted lists in a git repository and work in it with a coding agent (e.g. Claude Code), answering yes writes the skill files into .claude/skills/ so the agent can drive Ritual in this repository’s context. Pass --skills or --no-skills to make the choice without prompting (handy for scripted setups). With --force, existing skill files are overwritten; otherwise customized skill files are preserved. (During upgrades, already-installed skills are refreshed automatically — no --force needed.) You can also install or refresh them at any time with ritual skills install, or refresh just the already-installed ones — never adding new skills — with ritual skills update.

Generated Files

GitHub Actions

File	Description
`.github/workflows/deploy-site.yml`	GitHub Actions workflow for deploying to GitHub Pages (tracked)
`ritual.config.json` (`site` key)	Stores your settings and the Ritual version used — commit this file
`README.md`	Basic setup instructions for your site
`.gitignore`	Entries for `cache/`, `dist/`, `exports/`, the `.dist-build-`/`.dist-old-` build scratch directories, etc. (appended if the file already exists). A local-build deploy omits its built-site directory and un-ignores it instead.

Manual / None

File	Description
`ritual.config.json` (`site` key)	Stores your settings and the Ritual version used — commit this file
`README.md`	Basic setup instructions for your site
`.gitignore`	Entries for `cache/`, `dist/`, `exports/`, etc. (appended if the file already exists)

If a generated file already exists, you’ll be prompted before overwriting (or it is overwritten without prompting under --force). The README.md overwrite decision can also be made without a prompt via --overwrite-readme / --no-overwrite-readme, which take precedence over --force. In a headless run, an existing file with no decision flag is a usage error.

Version Tracking and Upgrade

init-site writes a site block into ritual.config.json recording your CI system, settings, and the current Ritual version. It also seeds the publish lists (includeDecks, includeCollections, includeWantedLists) with the ["*"] default — “publish everything” — which you can later narrow from the admin Settings page or with config set. Examples:

{
  "site": {
    "version": "0.1.0",
    "ciSystem": "github-actions",
    "deployMode": "publish-for-me",
    "distDir": "dist",
    "detectChanges": false,
    "includeDecks": ["*"],
    "includeCollections": ["*"],
    "includeWantedLists": ["*"]
  }
}

{
  "site": {
    "version": "0.1.0",
    "ciSystem": "github-actions",
    "deployMode": "publish-for-me",
    "distDir": "dist",
    "detectChanges": true
  }
}

{
  "site": {
    "version": "0.1.0",
    "ciSystem": "manual"
  }
}

Commit ritual.config.json so Ritual knows which version initialized the repository.

Upgrading

When you run ritual init-site after upgrading to a newer Ritual build, it detects the version change and prompts for confirmation before regenerating tracked managed files:

Ritual has been upgraded (0.1.0 → 0.2.0). Regenerate tracked managed files? (Y/n)

If you confirm, migrations run using your saved settings:

Upgrading from 0.1.0 to 0.2.0...
↻ Updated .github/workflows/deploy-site.yml
✓ Updated .gitignore
✓ ritual.config.json site section updated to 0.2.0
✓ Updated 7 Ritual agent skills in .claude/skills

An upgrade also refreshes .gitignore, which is how an existing scaffold picks up entries added by newer Ritual versions. It is the only way to get them short of --force, and it matters most for a local-build deploy: the !<distDir>/ un-ignore that keeps your committed built site out of .gitignore is appended here, so a scaffold created before that fix stops silently ignoring the directory the deploy workflow publishes.

Upgrades also refresh any agent skills already installed in .claude/skills so they track the new version. Only skills that are already present are rewritten — an upgrade never introduces skills you didn’t install. Pass --no-skills to leave them untouched, or --skills to (re)install the full set.

To skip the prompt and upgrade automatically (e.g. in a script), use --upgrade:

ritual init-site --upgrade

Running init-site when the recorded version already is the current one is a friendly no-op — it prints Already initialized with the current version (x.y.z); nothing to do. and exits 0, so an “ensure initialized” setup script can run it unconditionally.

In a headless run (prompts unavailable), a pending upgrade without --upgrade is a usage error naming the flag. Upgrades regenerate every tracked managed file from your saved settings, so workflows generated by older versions pick up template changes — for example, a workflow that still runs build-site --allow-refresh is rewritten to use --refresh auto.

Downgrade warning

If the current Ritual build is older than the version recorded in the site config, the command warns you and exits with a failure status without making changes:

Warning: The current Ritual build (0.1.0) is older than the version last used
to initialize this repository (0.2.0).
Use --force to re-initialize with current settings, or remove the "site" key
from ritual.config.json if you want to use this older version.

`--force`

Use --force (or -f) to bypass all version checks and re-run the full init, overwriting all generated files — including an existing README.md (pass --no-overwrite-readme to keep it). The fresh-init flags work here too, so a fully-flagged --force run never prompts:

ritual init-site --force --ci github-actions --deploy publish-for-me --no-change-detection --currency usd

Exit Codes

Code	Meaning
`0`	Files generated, the upgrade was applied, or the repository was already initialized with the current version (nothing to do)
`1`	Failed to write `ritual.config.json`, or the current build is older than the version that initialized the repository
`2`	A prompt was cancelled or declined, a flag was invalid or contradictory (including fresh-init flags on an already-initialized repository), or a headless run was missing a required flag

Customizing the Ritual Version (GitHub Actions)

When using the “Publish for me” workflow, the action downloads the latest Ritual release by default. To pin a specific version:

Go to your repository on GitHub
Navigate to Settings → Secrets and variables → Actions → Variables
Create a repository variable named RITUAL_VERSION
Set it to the desired release tag (e.g. v1.0.0)

The workflow checks this variable on each run and downloads the specified version instead of the latest. The binary is cached between runs using GitHub Actions caching, keyed by version — so if the version hasn’t changed since the last run, no download occurs.

Examples

Initialize a new site project:

mkdir my-decks && cd my-decks
git init
ritual init-site
ritual edit

The generated README.md walks new visitors through creating decks, collections, and wanted lists with ritual edit, and links to this documentation site.

After setup with GitHub Actions, enable GitHub Pages in your repo settings:

Go to Settings → Pages
Under Source, select GitHub Actions
Push to main to trigger your first deploy