Skip to content
Clonit

Quick Start

This guide walks through the full first-use workflow: initializing Clonit, adding a target, building a snapshot, and loading it into a destination database.

Step 1: Initialize

Section titled “Step 1: Initialize”

Run config init to create the configuration file and SQLite metadata database:

Terminal window
clonit config init

This creates:

  • ~/.config/clonit/config.yaml with an auto-generated secret key
  • ~/.config/clonit/clonit.db SQLite database for metadata

Step 2: Add a Target

Section titled “Step 2: Add a Target”

A target defines a source database to snapshot and an optional destination database to load into:

Terminal window
clonit targets add \
  --name mydb \
  --src-url "postgres://user:pass@srchost:5432/mydb" \
  --dst-url "postgres://user:pass@localhost:5432/mydb_dev"

The source and destination URLs are encrypted at rest in the SQLite database using the secret key from your config.

Step 3: Verify Connectivity

Section titled “Step 3: Verify Connectivity”

Confirm that Clonit can reach both the source and destination databases, and that your local PostgreSQL tools are compatible with the server versions:

Terminal window
clonit targets verify mydb

This checks connectivity, detects local tool versions (pg_dump, pg_restore, psql), queries server versions, and reports any compatibility issues.

Step 4: Build a Snapshot

Section titled “Step 4: Build a Snapshot”

Build a snapshot of the source database:

Terminal window
clonit build mydb

This runs pg_dump in directory format against the source URL and stores the snapshot in the working directory (~/.clonit by default).

Step 5: Load a Snapshot

Section titled “Step 5: Load a Snapshot”

Load the most recent snapshot into the destination database:

Terminal window
clonit load mydb

Load a specific snapshot by index:

Terminal window
clonit load mydb 0

Load a raw SQL file directly:

Terminal window
clonit load mydb /path/to/file.sql

Step 6: List Targets and Snapshots

Section titled “Step 6: List Targets and Snapshots”

View all configured targets:

Terminal window
clonit targets

View snapshots for a specific target:

Terminal window
clonit snapshots mydb

Step 7: Start the Web UI (Optional)

Section titled “Step 7: Start the Web UI (Optional)”

Launch the web UI for a visual interface to manage targets, snapshots, analysis, and cloud features:

Terminal window
clonit serve

Open http://127.0.0.1:8484 in your browser. The web UI provides:

  • Dashboard with stats and recent snapshots
  • Target management with connection verification and tool compatibility checks
  • Snapshot management with push-to-cloud capability
  • AI-powered sanitization analysis (requires Anthropic API key)
  • Ephemeral sanitization testing in Docker containers
  • Cloud integration for team collaboration

See the serve command for details.

Next Steps

Section titled “Next Steps”