Scrybase

Commander intelligence for your decks, your collection, and your real pod meta.

Scrybase is a local-first Commander workbench for deck building, collection management, pod tracking, matchup notes, and long-term tuning. It helps you build from the cards you already own, record what actually happens on game night, and make better decisions with data from your own playgroup.

What Scrybase does

• Import and analyze decks with mana curve, pip, category, combo, and cut/upgrade insight
• Track your collection and see owned versus missing cards across your lists
• Run sessions, check in players, seat pods, record results, and review history
• Keep matchup notes tied to decks, commanders, opponents, and sessions
• Review deck, player, commander, and pod trends over time
• Use the browser app for day-to-day work, the TUI scaffold for terminal snapshots, and the CLI for operator workflows

Why it exists

Most Commander tools stop at deck lists or card inventories. Scrybase connects the parts that matter together:

• what you play
• what you own
• who you play against
• what actually wins

That means better upgrade decisions, cleaner pod context, and tuning that reflects your real meta instead of generic averages.

Core areas

Deck Lab

Import decks, inspect mana and role balance, track revisions, review combos, and spot cuts or upgrades.

Collection Base

Import your collection, compare it against every deck, and see card demand across your lists.

Pod Intel

Create sessions, register players and decks, generate fair pods, record results, and review game-night history.

Matchup Journal

Store notes for commanders, opponents, decks, and sessions so you have context before the next game starts.

Meta and tuning

Review performance trends, recurring threats, win conditions, and deck changes over time.

Quick start

Requirements

• Python 3.12+
• uv
• Bun
• Docker for the easiest local PostgreSQL bootstrap, or an existing PostgreSQL 16+ instance

Current runtime shape

Scrybase still ships on a PostgreSQL-backed Python runtime while the approved rewrite target in BUILD.md moves the repo toward Bun + TypeScript + Astro + Vue + Elysia + Zod + PostgreSQL + Docker Compose + Caddy.

The rewrite foundation now also exists under apps/, packages/, and deploy/, but that skeleton is not the shipped runtime yet.

What ships today:

• src/app is the live FastAPI backend, JSON contract layer, compatibility HTML surface, SQLAlchemy model set, and CLI source
• frontend/web is the Bun-managed Astro + Vue browser shell and the primary browser entrypoint
• frontend/tui is the Bun-managed OpenTUI operator scaffold
• migrations/ is the Alembic schema history for the live PostgreSQL database
• tests/ is the verification lane for routes, contracts, CLI flows, and domain services

The current Python backend, Python CLI expansion, legacy template surface, and OpenTUI scope are feature-frozen except for migration blockers and release-critical fixes.

Current-state reference docs:

• docs/legacy-runtime-baseline.md for shipped runtime ownership and feature-freeze rules
• docs/postgresql-inventory.md for the live schema, constraints, indexes, and token-bearing tables
• docs/operations.md for environment variables, startup commands, backup paths, and operator commands
• docs/smoke-flows.md for the parity smoke list that must survive the rewrite
• docs/frontend-migration-inventory.md for the detailed route and contract discovery map

Run locally with PostgreSQL

Bring up a disposable local PostgreSQL instance:

docker run --name scrybase-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=scrybase \
  -p 5432:5432 \
  -d postgres:16-alpine

Then configure Scrybase and start the Python backend:

uv sync
export SCRYBASE_DATABASE_URL=postgresql+psycopg://postgres:[email protected]:5432/scrybase
uv run alembic upgrade head
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

Open http://127.0.0.1:8000 if you want the compatibility FastAPI UI.

Run the Astro web shell

In a second terminal, install the Bun workspace dependencies and start the browser shell against the running backend:

bun install
SCRYBASE_BACKEND_URL=http://127.0.0.1:8000 bun run dev-web

Open http://127.0.0.1:4321 for the primary browser entrypoint.

The full Astro-owned route list and the remaining compatibility cleanup details are frozen in docs/legacy-runtime-baseline.md and docs/frontend-migration-inventory.md.

Run the OpenTUI operator shell

With the backend running locally, start the terminal scaffold in a third terminal:

bun install
SCRYBASE_BACKEND_URL=http://127.0.0.1:8000 bun run dev-tui

The current TUI scaffold signs in against the backend contract layer and renders authenticated overview, sessions, decks, and help screens. Setup still starts in the browser, and richer operator workflows have not been cut over.

If you do not set SCRYBASE_DATABASE_URL, Scrybase defaults to:

postgresql+psycopg://postgres:[email protected]:5432/scrybase

Runtime configuration

Environment variables use the SCRYBASE_ prefix. The short version is:

• SCRYBASE_DATABASE_URL sets the primary SQLAlchemy database URL.
• SCRYBASE_SECRET_KEY should be changed from the development default before any real deployment.
• SCRYBASE_DEBUG enables debug mode.
• SCRYBASE_HOST and SCRYBASE_PORT are available if you wrap startup in your own launcher.
• SCRYBASE_BACKEND_URL points the Astro and OpenTUI frontends at the backend.

See docs/operations.md for the full operational inventory, backup paths, and smoke commands.

CLI

Point the CLI at the same PostgreSQL database URL as the app:

export SCRYBASE_DATABASE_URL=postgresql+psycopg://postgres:[email protected]:5432/scrybase
uv run scrybasectl version
uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" deck list
uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" collection stats
uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" session list
uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" system status
uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" system backup

The CLI keeps version and help commands read-only. It will not create a database just to print version or usage.

--data-dir controls backup file destinations.

Operations

Current local state

Use the operator status command against the same database URL that the app uses:

uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" system status

That prints the backend, resolved database URL with secrets redacted, schema revision when present, database size, and core object counts for users, decks, collection cards, sessions, and matchup notes.

Backups

Create a backup with the built-in operator command:

uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" system backup

This writes a plain SQL dump under ~/.scrybase/backups/ by default, using local pg_dump when available and a Dockerized fallback when it is not.

You can always choose an explicit output path:

uv run scrybasectl --database-url "$SCRYBASE_DATABASE_URL" system backup \
  --output /srv/scrybase/backups/scrybase-$(date +%Y%m%d-%H%M%S).sql

Restore

Restore a backup into a target database with psql or the PostgreSQL Docker image:

psql postgresql://postgres:[email protected]:5432/scrybase < /path/to/backup.sql

Smoke checks

With the backend running locally:

curl http://127.0.0.1:8000/healthz
uv run scrybasectl version

Expected results:

• /healthz returns {"status":"ok"}
• scrybasectl version prints the installed Scrybase version

For a cheap end-to-end migration smoke path that bootstraps a disposable Docker PostgreSQL instance, migrates it, starts the FastAPI backend plus the Astro web shell, and exercises first-run auth, deck import plus detail, session create plus check-in plus detail, and CLI status plus backup flow:

./scripts/smoke-local.sh

Development verification

Backend checks:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

Web frontend checks:

bun run check-web
bun run test-web
bun run build-web

TUI frontend checks:

bun run check-tui
bun run test-tui

uv run pytest expects PostgreSQL. It will use SCRYBASE_TEST_DATABASE_URL when set, or start a disposable local Docker PostgreSQL container automatically.

Deployment

A production deployment is one application process plus a PostgreSQL database.

export SCRYBASE_DATABASE_URL=postgresql+psycopg://scrybase:[email protected]:5432/scrybase
export SCRYBASE_SECRET_KEY=replace-this-before-production
uv run alembic upgrade head
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

Put it behind your preferred edge service or private network path.

License

MIT. See LICENSE.