Litescope Docs

SQLite production operations — from doctor, diff, and schema to migrate, monitor, and fleet management, all from one binary.

Installation

macOS (Homebrew)

brew install croc100/tap/litescope

Linux

Download the latest binary from Releases, extract, and move to your PATH:

curl -fsSL https://github.com/croc100/Litescope/releases/latest/download/litescope_Linux_x86_64.tar.gz | tar xz
sudo mv litescope /usr/local/bin/

Windows

Download litescope_*_windows_amd64.zip from Releases, extract the .exe, and add its directory to PATH.

Verify

litescope --version

Licensing — free & open source

Litescope is free and open source under the GNU AGPL-3.0. The entire CLI and GUI — every command, fleet operation, migration, and automation — is unlocked for everyone. There is no license key and nothing to activate.

litescope license   # confirms the free/open-source status

doctor free

Run every single-database check at once and get a single verdict. doctor combines health (corruption, WAL bloat, fragmentation), advise (missing FK indexes, redundant indexes, full table scans), and lint (schema design anti-patterns). The "point it at a database and go oh" command — and it exits 1 when the database needs attention, so it drops straight into CI as a quality gate.

litescope doctor <database.db> [flags]

Flag	Default	Description
--deep	false	Use the exhaustive integrity_check instead of quick_check
--format	terminal	Output format: terminal, json, html
--out, -o	stdout	Write the report to a file (use with --format html)

Examples

# One-shot checkup
litescope doctor app.db

# Deep integrity check
litescope doctor app.db --deep

# Shareable, self-contained HTML report
litescope doctor app.db --format html -o report.html

diff free

Compare schema and data between two SQLite databases.

litescope diff <old.db> <new.db> [flags]

Flag	Default	Description
--format	text	Output format: text, json, markdown, html
--data	false	Include row-level data diff in addition to schema
--output, -o	stdout	Write output to file

Examples

# Human-readable schema diff
litescope diff prod-before.db prod-after.db

# JSON output for CI
litescope diff old.db new.db --format json

# Include data diff
litescope diff old.db new.db --data

# Save HTML report
litescope diff old.db new.db --format html -o report.html

schema free

Dump the schema of a single database — local, Turso, or D1. Beyond the human-readable and JSON views, --erd emits a Mermaid entity-relationship diagram you can paste straight into a GitHub README, where it renders automatically.

litescope schema <source> [flags]

Flag	Default	Description
--format, -f	terminal	Output format: terminal, json, mermaid
--erd	false	Shorthand for -f mermaid — output a Mermaid ER diagram

Examples

# Inspect a local database
litescope schema app.db

# Inspect a remote Turso database
litescope schema turso://TOKEN@ORG/DBNAME

# Mermaid ERD for a README
litescope schema app.db --erd

dump free

Write a database out as a standalone .sql file — schema plus data — that recreates it when replayed into sqlite3 or litescope migrate. Equivalent to the sqlite3 shell's .dump, with the same ordering and quoting; blob/NULL/quote-safe and round-trip verified. Works on local files (remote sources expose schema only).

litescope dump <database.db> [flags]

Flag	Default	Description
--out, -o	stdout	Write to a file instead of stdout
--schema-only	false	Dump DDL only (no INSERTs)
--data-only	false	Dump data only (no CREATE statements)
--table	—	Dump only this table and its data

Examples

# Full dump to a file
litescope dump app.db -o backup.sql

# Schema only (DDL)
litescope dump app.db --schema-only

# A single table and its rows
litescope dump app.db --table users

health free

Inspect a database for the operational faults that take down production SQLite: corruption, WAL bloat from a starved checkpoint, freelist fragmentation, and reachability. Exits 1 on any warning or critical finding.

litescope health <database.db> [flags]

Flag	Default	Description
--deep	false	Use the exhaustive integrity_check instead of the faster quick_check
--format	terminal	Output format: terminal, json

Examples

# Quick triage
litescope health app.db

# Exhaustive integrity check
litescope health app.db --deep

locks free

Diagnose database is locked / SQLITE_BUSY — the single most common SQLite production failure. The static check inspects journal mode, busy_timeout, locking mode, and WAL bloat, and prescribes the exact PRAGMA or DSN change. The live probe (--live) tells you whether a writer is holding the lock right now and which process owns the file. Exits 1 when the database needs attention or is currently locked.

litescope locks <source> [flags]

Flag	Default	Description
--live	false	Probe the current lock state instead of static config (local files)
--watch	false	Stream live lock-state changes until interrupted
--interval	1s	Poll interval for --watch
--format	terminal	Output format: terminal, json

Examples

# Static configuration diagnosis (local, D1, or Turso)
litescope locks app.db

# Is a writer holding the lock right now?
litescope locks app.db --live

snapshot / restore free

Point-in-time backups for local (and Turso) SQLite — the same "did you back up?" safety net that D1 gets from Time Travel. snapshot writes a consistent VACUUM INTO copy (safe even under WAL) into a sibling .litescope-snapshots/ directory; restore integrity-checks the snapshot and takes a pre-restore safety snapshot before overwriting.

litescope snapshot <db> [flags]
litescope snapshot list <db>
litescope restore <db> [flags]

Flag	Default	Description
--label	—	Optional label recorded in the snapshot name
--keep	0	Retention: keep only the N newest snapshots (0 = keep all)
--from	newest	(restore) Snapshot file to restore from
--no-safety-snapshot	false	(restore) Skip the pre-restore safety snapshot

Examples

litescope snapshot app.db --label before-migration
litescope snapshot app.db --keep 7
litescope snapshot list app.db
litescope restore app.db            # newest snapshot

autopilot free

The self-driving DBA. Derives safe maintenance and optimization actions — ANALYZE, PRAGMA optimize, missing foreign-key indexes, and (with --aggressive) VACUUM and redundant-index cleanup — and explains each in plain language. Dry-run by default; every real change is preceded by an automatic snapshot, so a run is one restore away from undo.

litescope autopilot <db> [flags]

Flag	Default	Description
--apply	false	Apply the safe actions (default: dry-run)
--aggressive	false	Also apply risky actions (VACUUM, drop redundant indexes)
--queries	—	File of SQL queries for EXPLAIN-based advice
--fleet	—	Run across every database in a fleet config
--format	terminal	Output format: terminal, json

Examples

# Show the plan, change nothing
litescope autopilot app.db

# Apply the safe actions (snapshot taken first)
litescope autopilot app.db --apply

# Whole fleet
litescope autopilot --fleet litescope.fleet.yaml --apply

advise free

Recommend indexes and flag performance problems — the ones AI-generated schemas ship by default. Schema rules need no query input: point at a database and get instant advice. Exits 1 when any warning is found.

litescope advise <database.db> [flags]

Flag	Default	Description
--query	—	Analyze a single SQL query for full table scans
--sql	—	Analyze every query in a .sql file
--format	terminal	Output format: terminal, json

What it catches

• fk-no-index — a foreign key with no index. SQLite, unlike MySQL, does not auto-index FK columns, so every join or cascade scans the whole table.
• redundant-index — an index whose columns are already a leading prefix of another.
• full-scan — a supplied query that does a full table scan (via EXPLAIN QUERY PLAN).

Examples

# Point-and-shoot schema analysis
litescope advise app.db

# Check a specific query
litescope advise app.db --query "SELECT * FROM orders WHERE user_id = ?"

lint free

Check a schema for the structural mistakes that ship by default — especially in hand-written or AI-generated schemas. lint looks only at the schema shape (never data or queries), so it is fast and safe in CI. By default it exits 1 on warnings; --strict also fails on info findings. For index/performance problems use advise; for both plus health, doctor.

litescope lint <database.db> [flags]

Rule	What it catches
no-primary-key	A table with no PRIMARY KEY (no stable row identity)
untyped-column	A column with no declared type (BLOB affinity)
not-strict	A non-STRICT table (types are advisory, silently coerced)
autoincrement-overhead	AUTOINCREMENT where plain INTEGER PRIMARY KEY would do
non-integer-pk	A single-column PK that does not alias the rowid

Flag	Default	Description
--format	terminal	Output format: terminal, json
--strict	false	Exit 1 on info findings as well as warnings

Examples

# Lint a schema
litescope lint app.db

# Fail CI on info findings too
litescope lint app.db --strict

validate free

Lock a migration to a spec and enforce it in CI: validate compares the actual changes a migration made against an expected set, so an unplanned change fails the build. Generate the expectation file once from a known-good migration with validate init, then check every run with validate run.

Command	Description
validate init <before.db> <after.db>	Generate an expectation file from the actual diff (run once after a manual migration); writes migration.yaml by default (-o to override)
validate run	Compare actual migration changes against the expected spec

Flag (run)	Default	Description
--expect, -e	—	Path to the expectation YAML/JSON file (required)
--format, -f	terminal	Output format: terminal, json
--strict	true	Fail on any unexpected change

Examples

# Capture the expected changes once
litescope validate init before.db after.db -o expected.yaml

# Enforce in CI
litescope validate run -e expected.yaml

check free

Verify a backup database. The PRAGMA integrity check and a comparison against a single reference (--against, with optional --data), batch verification of more than one file, and saving a report (--save-report) are all free.

litescope check <backup.db> [--against <reference.db>] [flags]

Flag	Default	Description
--against	—	Reference DB to compare schema against
--data	false	Also compare row counts per table
--save-report	—	Append the result to a JSONL history file
--format	text	Output format: text, json

Examples

# Integrity check only (free)
litescope check backup.db

# Schema match against production (free)
litescope check backup.db --against prod.db

# Include row count comparison (free)
litescope check backup.db --against prod.db --data

# Batch-verify many backups + save a report
litescope check backups/*.db --against prod.db --save-report report.jsonl

migrate free

Generate migration SQL by diffing two databases, then apply it safely with backup and rollback. Generation always prints a blast-radius analysis first.

generate

litescope migrate <old.db> <new.db> [flags]

Flag	Default	Description
--output, -o	stdout	Write SQL to file
--force	false	Write the file even when the migration is destructive

Each operation is classified before the SQL — SQLite locks the entire file for a table rebuild, so the estimated write-lock matters:

  Blast radius analysis
  ─────────────────────────────────────────────────────────────
  ✓  CREATE TABLE audit_logs            new table — instant
  ⚠  TABLE REBUILD orders               50.0K rows, 3 index(es) → ~1s write-lock
  ✗  DROP TABLE sessions                12,400 rows permanently deleted
  ─────────────────────────────────────────────────────────────

apply

litescope migrate apply <db> <migration.sql> [flags]

Flag	Default	Description
--dry-run	false	Run inside a transaction and roll back — validate without committing
--backup-dir	same dir as db	Where to store the automatic pre-migration backup
--verify	—	After applying, verify the schema matches this reference DB

Examples

# Generate SQL with blast-radius report
litescope migrate old.db new.db -o migration.sql

# Preview before applying (transaction + rollback)
litescope migrate apply prod.db migration.sql --dry-run

# Apply (creates VACUUM INTO backup automatically)
litescope migrate apply prod.db migration.sql

Versioned migrations

Beyond ad-hoc diffs, Litescope manages an ordered, versioned migration history — the Atlas/Flyway workflow. Migration files live in a migrations/ directory (0001_name.sql, 0002_…) and applied versions are tracked in a litescope_schema_migrations table.

Command	Tier	Description
migrate new <name>	free	Create the next numbered migration file (use --from/--to to pre-fill from a diff)
migrate status <db>	free	Show applied vs pending migrations; flags history drift
migrate up <db>	free	Apply all pending migrations in order, each through the safe pipeline

# Generate a versioned migration from a schema change
litescope migrate new add_users --from prod.db --to desired.db

# See what's pending
litescope migrate status prod.db

# Apply pending migrations (records each in the tracking table)
litescope migrate up prod.db

monitor

Baseline a known-good schema, then check for drift. The watch subcommand runs continuously and can alert on changes.

snapshot

litescope monitor snapshot <db> [flags]

Flag	Default	Description
--output, -o	baseline.json	Path to write the baseline snapshot

check

litescope monitor check <db> [flags]

Flag	Default	Description
--baseline, -b	baseline.json	Path to the baseline snapshot
--format	text	Output format: text, json

watch free

Watch a single local database or remote targets (Turso/D1), with webhook alerts (--webhook) to Slack and Discord — all free.

litescope monitor watch <db> [flags]

Flag	Default	Description
--baseline, -b	baseline.json	Path to the baseline snapshot
--interval	30s	Poll interval (e.g. 10s, 1m, 5m)
--webhook	—	Slack or Discord webhook URL for drift alerts

Examples

# Baseline
litescope monitor snapshot prod.db -o baseline.json

# One-off check
litescope monitor check prod.db -b baseline.json

# Continuous watch with Slack alert
litescope monitor watch prod.db -b baseline.json \
  --interval 1m \
  --webhook $SLACK_WEBHOOK_URL

fleet

Operate an entire Turso org or Cloudflare D1 account as one unit. discover writes a litescope.fleet.yaml config; every other subcommand reads it and runs in parallel. The lifecycle: diagnose (fingerprint, health), then treat (converge, recover).

Every fleet subcommand — read-only diagnosis (fingerprint / health) and every fix action — is free, on a fleet of any size.

discover

Query the provider API for every database and write the fleet config.

litescope fleet discover <turso|d1> [flags]

Flag	Default	Description
--org	—	Turso org slug
--account	—	Cloudflare account ID (D1)
--token	—	Platform API token (Turso platform token or CF API token)
--db-token	—	Turso database/group auth token applied to each DSN

snapshot & check

Capture baselines, then detect schema drift across the whole fleet. check exits 1 if any database drifted — drop it into CI.

litescope fleet snapshot
litescope fleet check [--tag group:prod] [--format json]

fingerprint free

Cluster the fleet by schema. The largest cluster is canonical; every other shows exactly how it drifted. Exits 1 when more than one schema is found.

litescope fleet fingerprint

converge

Generate and apply the migration that brings every drifted database onto canonical — staged, halting on failure. Destructive convergence requires --force.

litescope fleet converge --dry-run        # plan + validate
litescope fleet converge --canary 5       # fix the first 5, then stop
litescope fleet converge --to canonical.db

health free

Parallel fault triage — corruption, WAL bloat, fragmentation, reachability — sorted worst-first. Exits 1 on any fault. Run it on a schedule to get paged on fleet faults, or continuously with --watch.

litescope fleet health [--deep] [--tag region:eu]
litescope fleet health --webhook $SLACK_URL          # one-shot alert (cron)
litescope fleet health --watch --interval 5m         # continuous monitoring
litescope fleet health --watch --webhook $URL --recover  # detect → alert → auto-restore

Flag	Description
--watch	Run continuously on an interval
--interval	Watch interval (e.g. 30s, 5m, 1h)
--webhook	POST a fault alert to this URL (Slack-compatible)
--recover	Auto-restore critically faulted databases from backup

blast-radius

Map each critically faulted database to the cohorts it shares (Turso groups, regions — any tag). One corrupt database in a group often means the whole group's shared infrastructure is suspect — this shows who else to check.

litescope fleet blast-radius

recover

Restore critically faulted databases from their most recent verified backup; quarantine the unrecoverable so they're excluded from future fleet ops.

litescope fleet recover --dry-run
litescope fleet recover

migrate

Roll one migration out across the fleet, staged and fail-closed, halting at the first failure.

litescope fleet migrate add_index.sql --canary 5

Example workflow

# 1. Register every database in a Turso org
litescope fleet discover turso --org my-org \
  --token $TURSO_API_TOKEN --db-token $TURSO_GROUP_TOKEN

# 2. Diagnose: how many schemas, and what's broken?
litescope fleet fingerprint
litescope fleet health

# 3. Treat: converge drift, recover faults
litescope fleet converge --dry-run
litescope fleet recover

MCP server free

Let an AI agent drive Litescope. litescope mcp runs a Model Context Protocol server over stdio, so Claude Desktop, Claude Code, or any MCP client can call Litescope as a tool — "use litescope to check the health of ./app.db".

Setup (Claude Desktop)

Add Litescope to claude_desktop_config.json:

{
  "mcpServers": {
    "litescope": { "command": "litescope", "args": ["mcp"] }
  }
}

Restart Claude Desktop. Litescope's tools then appear to the model.

Exposed tools

All tools are read-only — an AI can diagnose your databases freely, but never mutates them.

Tool	What it does
litescope_health	Inspect a database for corruption, WAL bloat, fragmentation
litescope_schema	Load tables, columns, and indexes
litescope_diff	Compare two databases
litescope_advise	Recommend indexes; flag un-indexed FKs and full table scans
litescope_migrate_plan	Migration SQL + blast-radius (write-lock estimate) — no apply
litescope_check	Backup integrity; schema match vs a reference
litescope_fingerprint	Cluster a fleet by schema
litescope_fleet_health	Parallel fault triage across a fleet

Hosted dashboard subscription

Everything above is free and runs on your machine, including the local dashboard (litescope serve). The hosted dashboard is the one paid offering: your entire fleet — thousands of databases — on one always-on, multi-user screen, with time-series drift history and alerts. It receives metadata only (health, schema fingerprint, drift); your rows never leave your machines.

How onboarding works

1. Subscribe on the pricing page (Hosted or Scale — pick your tier at checkout).
2. Check your email. Provisioning is automatic: you'll get a welcome email with a one-time sign-in link and your push API key (lsk_…, shown once — store it safely).
3. Sign in at the link to open your dashboard. You can request a fresh sign-in link anytime from the login page.
4. Connect the CLI on the machine(s) that can reach your databases, and push:

   export LITESCOPE_CLOUD_URL=https://app.litescope.crode.net
   export LITESCOPE_CLOUD_KEY=lsk_your_key_here
   litescope push                 # one-shot; preview with --dry-run

5. Schedule it. push sends a single snapshot — run it on a cron job or systemd timer (e.g. every 5 minutes) to keep the dashboard current.

litescope push

Collects each database's health report and schema fingerprint and POSTs the metadata to your hosted dashboard. Only metadata is transmitted — never customer rows.

litescope push [flags]

Flag	Default	Description
--endpoint	$LITESCOPE_CLOUD_URL	Hosted dashboard base URL
--key	$LITESCOPE_CLOUD_KEY	API key (lsk_…) from your welcome email
--config	litescope.fleet.yaml	Fleet config to push
--tag	—	Only push databases matching this tag
--dry-run	false	Print the payload without sending

Desktop GUI

The GUI app bundles all CLI operations in a visual interface. It ships as part of the same binary download — run litescope gui to launch, or double-click the .app on macOS.

Named connections

Add databases by clicking + Add in the sidebar. Named connections are unlimited.

Tools

• Diff — visual schema and data diff between two databases
• Explorer — browse tables and query rows
• Check — validate a backup against a reference
• Migrate — blast-radius analysis, generate and apply with dry-run
• Monitor — snapshot, check drift, run continuous watch
• Fleet — discover, fingerprint, converge, health, and recover Turso / D1 databases
• Fleet Map — every database as a cell in a living map, colored by health or schema cluster

Changelog

v0.3.0 2026-06-19

• migrate: blast-radius analysis — every operation classified Safe/Risky/Destructive with an estimated table-rebuild write-lock
• fleet fingerprint: cluster the fleet by schema and see drift from canonical
• fleet converge: auto-generate and stage the migration that fixes drift
• fleet health + health: parallel fault triage — corruption, WAL bloat, fragmentation
• fleet recover: restore faulted databases from backup; quarantine the unrecoverable
• GUI: the full fleet lifecycle — fingerprint, converge, health, and recover
• mcp: MCP server — let Claude and other AI agents call Litescope as read-only tools
• advise: index & query advisor — flags un-indexed foreign keys, redundant indexes, and full table scans
• migrate new/status/up: versioned migration workflow with a tracking table and checksum history-drift detection
• license: show the active tier (Free / Pro)
• GUI: fleet topology map — every database colored by health or schema cluster
• fleet blast-radius: map a fault to the shared cohort (group/region) at risk
• fleet health --watch / --webhook / --recover: scheduled monitoring, Slack alerts, auto-recovery
• License verification cached (24h) with a 14-day offline grace — the server is no longer a hard dependency

v0.2.0 2026-06-16

• GUI: Monitor Watch — continuous drift detection with live event feed
• GUI: Fleet panel — Turso and D1 discover, snapshot, parallel check
• GUI: Free/Pro tier — 3-connection limit, Pro gate on Monitor and Fleet
• Lemon Squeezy payment integration — $99/year Pro subscription
• Online license verification via Cloudflare Worker
• Binary releases via litescope-dist + Homebrew tap

v0.1.0 2026-05-01

• Initial release: diff, check, migrate, monitor, fleet CLI
• GUI desktop app (Wails/Go + React)
• Named connections sidebar