Documentation

Install, configure, and start backing up in under a minute.

Quick start

Three commands. That's it.

1. Install

curl -sSL https://raw.githubusercontent.com/calmbackup/cb-cli/master/install.sh | bash

Downloads a single static binary, creates a config template, and sets up a daily cron job. No sudo required.

2. Configure

calmbackup init

The setup wizard asks for your API key and database credentials, generates an encryption key, and writes the config.

3. Backup

calmbackup run

Run your first backup. After this, backups run daily at 2:00 AM automatically via cron.

Installation details

The CLI is a single static binary with no runtime dependencies. The installer auto-detects whether you're running as root or a regular user.

	As root	As regular user
Binary	`/usr/local/bin/`	`~/.local/bin/`
Config	`/etc/calmbackup/`	`~/.config/calmbackup/`
Backups	`/var/backups/calmbackup/`	`~/.local/share/calmbackup/`
Cron	`/etc/cron.d/calmbackup`	user crontab

Supported databases

MySQL (via mysqldump)
PostgreSQL (via pg_dump)
SQLite (via sqlite3)

Supported architectures

Linux amd64, Linux arm64

Commands

Run a backup

calmbackup run

List backups

calmbackup list

Restore a backup

calmbackup restore <backup-id>

Check status

calmbackup status

Global flags

`--config <path>`	Override config file location
`--verbose, -v`	Verbose output
`--quiet, -q`	Suppress non-error output (useful for cron)

Configuration reference

Most users won't need to edit the config file directly — calmbackup init handles it. But if you need fine-grained control:

Config file location

Searched in order:

--config <path> flag (explicit)
/etc/calmbackup/calmbackup.yaml (system-wide)
~/.config/calmbackup/calmbackup.yaml (user-level)
./calmbackup.yaml (current directory)

Full config example

api_key: "ak_live_..."
encryption_key: "64-char-hex-key"

database:
  driver: mysql         # mysql | pgsql | sqlite
  host: "127.0.0.1"
  port: 3306
  database: "myapp"
  username: "root"
  password: "secret"
  # path: "/path/to.db" # sqlite only

directories:            # optional
  - /var/www/app/uploads

local_path: "/var/backups/calmbackup"
local_retention_days: 7

Configuration fields

Field	Required	Description
`api_key`	Yes	Your API key from the dashboard.
`encryption_key`	Yes	Generated locally by `calmbackup init`. Never sent to our servers.
`database.driver`	Yes	`mysql`, `pgsql`, or `sqlite`
`directories`	No	Additional directories to include in every backup.
`local_retention_days`	No	Days to keep local backups. Default: 7.

Scheduling

The installer sets up a daily cron job at 2:00 AM automatically. To customize:

# Root install
sudo nano /etc/cron.d/calmbackup

# User install
crontab -e

# View logs
journalctl -t calmbackup

PHP / Laravel Package

Laravel applications can use the Composer package for artisan commands and scheduler integration. The PHP package uses the same encryption format and API, so backups are compatible between the CLI and the package.

Install

composer require calmbackup/backup
php artisan backup:install

Environment variables

CALMBACKUP_API_KEY=your-api-key
CALMBACKUP_ENCRYPTION_KEY=your-encryption-key

Artisan commands

php artisan backup:run       # Run a backup
php artisan backup:list      # List backups
php artisan backup:restore   # Restore a backup
php artisan backup:status    # Check status

Scheduler

The package registers a daily scheduled task automatically. Make sure the scheduler is running:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Requirements

PHP 8.2+
ext-openssl, ext-curl
Laravel 10–13 (or any PHP app via vendor/bin/calmbackup)

API Reference

Most users never interact with the API directly. Both the CLI and PHP package handle all API communication. All endpoints require a Authorization: Bearer YOUR_API_KEY header.

POST /api/v1/upload-url

Get presigned upload URL

POST /api/v1/backups/{id}/confirm

Confirm upload completed

GET /api/v1/backups

List backups

GET /api/v1/backups/{id}

Get backup + download URL

DELETE /api/v1/backups/{id}

Delete backup

GET /api/v1/account

Account info