Getting Started

Installation

Checkpoint installs globally on your system. One install covers all your projects.

                    git clone https://github.com/fluxcodestudio/Checkpoint.git
cd Checkpoint
./bin/install-global.sh
                

The installer:

Adds checkpoint and backup-now to your PATH
Starts a background daemon that runs hourly backups
Creates global config at ~/.config/checkpoint/config.sh
Installs the macOS menu bar dashboard (macOS only)

That's it. After install, Checkpoint runs silently in the background. You can use the Dashboard or CLI to manage everything — or just let it run.

Your First Backup

Navigate to any project directory and run:

                    cd ~/my-project
backup-now
                

On first run, Checkpoint will:

Auto-create a .backup-config.sh in your project
Register the project for automatic hourly backups
Run an immediate backup of files and any detected databases

From this point on, your project is backed up every hour automatically. No further action needed.

How It Runs

Checkpoint uses a system-level background daemon:

macOS: launchd agent — starts on login, runs hourly
Linux: systemd user service — same behavior
Fallback: cron job if neither is available

The daemon loops through all registered projects and backs up any that have changed since the last run. No CPU or disk usage when nothing has changed.

Set it and forget it. The daemon auto-starts on boot, auto-restarts on crash, and has a built-in watchdog that monitors its health. If no backup runs for 24 hours, you'll get a notification.

Managing Projects

Adding Projects

There are three ways to add a project to Checkpoint:

Option 1: Run backup-now (simplest)

                    cd /path/to/your/project
backup-now
                

The project is automatically registered and will be included in all future hourly backups.

Option 2: Dashboard

Open the Checkpoint menu bar app and use the settings to manage registered projects. Projects appear automatically after their first backup.

Option 3: Configure manually

checkpoint --project /path/to/your/project

This opens the interactive configuration wizard for that specific project.

Multiple projects? Just run backup-now in each project directory once. After that, the daemon handles all of them automatically on the hourly schedule.

Removing Projects

To stop backing up a project, remove it from the registry:

                    # View all registered projects
checkpoint --status

# Remove a project's .backup-config.sh to unregister
rm /path/to/project/.backup-config.sh
                

Existing backups are preserved — only future backups stop.

Per-Project Settings

Each project has a .backup-config.sh file in its root directory. You can edit it directly or use the wizard:

checkpoint --project

Common settings:

Setting	Default	Description
`BACKUP_DIR`	`./backups`	Where backups are stored
`DB_TYPE`	auto-detected	Database engine (sqlite, postgres, mysql, mongodb)
`BACKUP_CRITICAL_FILES`	`true`	Back up .env, credentials, keys
`RETENTION_DAYS_DB`	`30`	Days to keep database backups
`RETENTION_DAYS_FILES`	`90`	Days to keep archived file versions

Global Settings

Global defaults apply to all projects unless overridden by per-project config.

                    # Edit via CLI
checkpoint --global

# Or edit directly
nano ~/.config/checkpoint/config.sh
                

Or use the Dashboard Settings (⌘,) to change these visually — no config files needed.

Key global settings:

Backup interval — How often the daemon runs (default: 60 min)
Compression level — gzip level for database backups (1-9)
Desktop notifications — On/off, failure-only mode
Cloud sync — Provider, encryption, what to upload
Debug mode — Verbose logging for troubleshooting

Cloud Backup

Setting Up Cloud Sync

Checkpoint supports two cloud sync methods:

Method 1: Direct folder sync (simplest)

Point Checkpoint at a synced cloud folder (Dropbox, iCloud Drive, Google Drive, OneDrive). Files are copied there and your cloud provider handles the upload.

                    # In global config (~/.config/checkpoint/config.sh)
CLOUD_FOLDER_ENABLED=true
CLOUD_FOLDER_PATH="/Users/you/Dropbox/Backups/Checkpoint"
                

Method 2: rclone (advanced)

Uses rclone for direct API uploads. Supports 40+ cloud providers including S3, Backblaze, and encrypted remotes.

                    # Install rclone
brew install rclone

# Configure a remote
rclone config

# In global config
CLOUD_RCLONE_ENABLED=true
CLOUD_RCLONE_REMOTE="mydropbox"
CLOUD_RCLONE_PATH="Backups/Checkpoint"
                

Recommended: Direct folder sync is easier. Use rclone if you need S3/Backblaze, bandwidth limiting, or encrypted remotes.

Supported Cloud Providers

Provider	Free Tier	Method
Dropbox	2 GB	Folder sync or rclone
Google Drive	15 GB	Folder sync or rclone
iCloud Drive	5 GB	Folder sync
OneDrive	5 GB	Folder sync or rclone
S3 / Backblaze B2	Varies	rclone only

A typical project uses ~65 MB/month for database backups and critical files — fits easily in any free tier.

Encryption & Compression

Cloud backups are compressed and encrypted before upload using age encryption and gzip compression.

                    # One command to set up encryption
checkpoint encrypt setup
                

This generates an encryption key at ~/.config/checkpoint/age-key.txt and enables encryption globally.

Compression Pipeline

Before encryption, compressible files (text, source code, configs) are gzip-compressed to reduce cloud storage usage. Already-compressed formats (images, video, archives, fonts) skip compression and are encrypted directly.

Text files: file → gzip → age → .gz.age
Binary files: file → age → .age

Parallel Encryption

When backing up 100+ files, encryption runs in parallel across multiple CPU cores (auto-detected, uses half your cores). Small backups use sequential processing to avoid overhead.

Cloud-only: Local backups stay unencrypted for fast access. Only cloud-synced files are encrypted.
Zero-knowledge: Your cloud provider cannot read your backup data.
Toggle anytime: Enable/disable from the Dashboard settings or CLI.

Keep your key safe. If you lose ~/.config/checkpoint/age-key.txt, your encrypted cloud backups cannot be recovered. There is no recovery mechanism. Back up this key separately.

Cloud Restore

Browse, search, and download files from your cloud backups — auto-decrypted and decompressed on download.

                    # List all cloud backups for a project
checkpoint cloud list MyProject

# Browse files interactively (fzf or numbered list)
checkpoint cloud browse MyProject

# Browse the latest backup directly
checkpoint cloud browse MyProject --latest

# Download a specific file (auto-decrypted)
checkpoint cloud download .env --project MyProject --backup-id latest

# Download everything as a zip
checkpoint cloud download-all --project MyProject --zip
                

Downloaded files are automatically decrypted and decompressed. They appear in ~/Downloads by default, or specify a directory with --output.

Cross-computer restore: Run checkpoint cloud setup on a new machine to import your encryption key and configure cloud access. Then browse and restore any backup from the cloud.

Dashboard

Menu Bar App

The Checkpoint Dashboard is a native SwiftUI app that lives in your macOS menu bar. It's installed automatically during setup.

Menu bar widget — Click the icon to see all projects, status, file counts, and last backup time
Live progress — Watch backups run in real-time
Native notifications — macOS desktop notifications on backup failures and staleness (24h without backup)
One-click actions — Backup All, Pause/Resume, per-project context menus
Keyboard shortcuts — ⌘B Backup All, ⌘R Refresh, ⌘, Settings

Right-click any project for quick actions: Backup Now, Reveal in Finder, View Backup Folder, View Log, Enable/Disable.

Notifications

Checkpoint sends native macOS desktop notifications (via osascript) for:

Backup failures — immediate alert with error details
Staleness warnings — no successful backup in 24 hours
Critical alerts — no successful backup in 72 hours

Configure in Dashboard settings or global config:

                    DESKTOP_NOTIFICATIONS=true    # Enable/disable
NOTIFY_ON_FAILURE_ONLY=false  # Only notify on failures
                

Notification cooldowns prevent alert fatigue (4h for warnings, 2h for critical).

Dashboard Settings

Press ⌘, in the Dashboard to open settings. Everything you can configure in config files, you can configure here:

Schedule — Backup interval, idle threshold
Retention — Database and file retention periods
What to Backup — Toggle .env files, credentials, IDE settings
Cloud Encryption — Enable/disable with one switch
Notifications — Desktop notifications, failure-only mode
Advanced — Compression level, debug logging

Changes are saved to ~/.config/checkpoint/config.sh and take effect on the next backup cycle.

CLI Reference

Commands

Command	Description
`backup-now`	Run an immediate backup in the current directory
`checkpoint`	Open the interactive TUI dashboard
`checkpoint --status`	Show status of all registered projects
`checkpoint --global`	Edit global settings
`checkpoint --project`	Configure the current project
`checkpoint --update`	Check for Checkpoint updates
`checkpoint verify`	Verify backup integrity
`checkpoint diff`	Compare working directory with last backup
`checkpoint encrypt setup`	Generate key and enable encryption
`checkpoint encrypt status`	Show encryption status
`checkpoint cloud list [PROJECT]`	List available cloud backups
`checkpoint cloud browse PROJECT`	Browse and download cloud backup files
`checkpoint cloud download FILE`	Download a file from cloud (auto-decrypted)
`checkpoint cloud download-all`	Download entire backup (optional --zip)
`checkpoint cloud setup`	Configure cloud access on a new machine

Search & Browse

                    # Search backup history for a file path or pattern
checkpoint search "app.py"

# Browse backup snapshots interactively (requires fzf)
checkpoint browse

# View all versions of a specific file
checkpoint history src/app.py

# Interactive version picker
checkpoint history -i src/app.py
                

Restoring Files

Restore files from the most recent backup or a specific version:

                    # Browse and restore interactively
checkpoint browse

# Restore from a specific backup
cp backups/archived/src/app.py.20250215_104500 src/app.py

# Restore a database
gunzip -k backups/databases/MyApp-2025.02.15-10.45.12.db.gz
                

Local backups are unencrypted and stored in plain files — you can always access them directly without any special tools.

Advanced

Database Backup

Checkpoint auto-detects databases in your project and uses the proper dump tool:

Database	Detection	Tool Used
SQLite	`.db`, `.sqlite` files	`sqlite3 .dump`
PostgreSQL	Connection string in .env	`pg_dump`
MySQL	Connection string in .env	`mysqldump`
MongoDB	Connection string in .env	`mongodump`

Remote databases (Neon, Supabase, PlanetScale, MongoDB Atlas) are supported — Checkpoint reads connection details from your .env file.

Docker Support

                    # List detected Docker databases
checkpoint docker-volumes list

# Backup Docker volumes
checkpoint docker-volumes backup

# Restore a Docker volume
checkpoint docker-volumes restore
                

Checkpoint reads your docker-compose.yml to find database containers. It can auto-start Docker Desktop if it's not running, and stop it after backup if needed.

Linux Setup

On Linux, Checkpoint uses systemd user services instead of launchd:

                    # Installation is identical
./bin/install-global.sh

# Manage the daemon via systemctl
systemctl --user status checkpoint-daemon
systemctl --user restart checkpoint-daemon
                

If systemd isn't available, Checkpoint falls back to a cron job.

Uninstalling

./bin/uninstall-global.sh

This removes the daemon, PATH entries, and the menu bar app. Your existing backups and project configs are not deleted — you can re-install later and pick up where you left off.