Commands

auth set-key

Set your API key for authentication.

coldplane auth set-key --key <api-key>

Option	Required	Description
`--key`, `-k`	Yes	API key (recommended format: `<id>:<secret>`)

Your credentials are saved to ~/.coldplane/config.json.

auth whoami

Show the currently authenticated user.

coldplane auth whoami

backup create

Archive one or more tables from your database.

coldplane backup create [options]

Option	Required	Description
`--db-url`, `-d`	Yes	Database connection string (`postgres://` or `mysql://`)
`--tables`	Yes	Comma-separated list of table names to archive
`--name`	No	Human-friendly name for the backup (auto-generated if omitted)
`--chunk-size`	No	Rows per chunk (default: `2500000`)
`--workers`	No	Number of parallel workers (default: `4`)
`--format`, `-f`	No	Export format (default: `parquet`)
`--where`	No	SQL WHERE clause to filter rows (e.g. `"created_at < '2025-01-01'"`)
`--local`	No	Store backup locally instead of uploading to ColdPlane Cloud. No account or API key required.

Example:

coldplane backup create \
  --db-url "postgres://user:pass@host:5432/mydb" \
  --tables "events,logs"

Local backup (no account required):

coldplane backup create --local \
  --db-url "postgres://user:pass@host:5432/mydb" \
  --tables "events,logs"

Local backups are saved to ~/.coldplane/backups/<name>/ as Parquet files.

backup list

List existing backups. Aliases: backup ls

coldplane backup list [options]

Option	Required	Description
`--limit`, `-n`	No	Max number of backups to display (default: `10`)
`--all`	No	Show all backups (overrides `--limit`)
`--status`	No	Filter by status: `running`, `completed`, `failed`
`--db`	No	Filter by database name
`--table`	No	Filter by table name
`--name`	No	Filter by backup name
`--local`	No	List local backups only

backup describe

Show detailed information about a backup. Aliases: backup get

coldplane backup describe <backup-id> [--json]

Option	Required	Description
`--json`	No	Output raw JSON instead of formatted table

backup delete

Delete a backup. Aliases: backup rm

coldplane backup delete <backup-id>

Option	Required	Description
`--local`	No	Delete a local backup by name

Delete a local backup:

coldplane backup delete --local my_backup_name

backup restore

Restore archived data into a target database.

coldplane backup restore [options]

Option	Required	Description
`--backup-id`	Yes	Backup ID to restore from
`--table`	Yes	Target table name in the destination database
`--to`	Yes	Target database connection string (`postgres://` or `mysql://`)

Example:

coldplane backup restore \
  --backup-id bck_abc123 \
  --table events_restored \
  --to "postgres://user:pass@host:5432/mydb"

query run

Execute a SQL query against an archived backup.

coldplane query run [options]

Option	Required	Description
`--backup-id`, `-b`	Yes	Backup ID to query
`--table`, `-t`	No	Table name
`--sql`, `-s`	Yes	SQL query (a default `LIMIT` is applied if omitted)
`--output`, `-o`	No	Output format: `table`, `json`, or `csv` (default: `table`)
`--export`	No	Export full results to a downloadable file
`--format`	No	Export file format: `csv` or `parquet` (default: `csv`)
`--local`	No	Query a local backup directly on your machine. No account or API key required.

Example:

coldplane query run \
  --backup-id bck_abc123 \
  --table events \
  --sql "SELECT user_id, COUNT(*) FROM events GROUP BY user_id" \
  --output table

Local query (no account required):

coldplane query run --local \
  --backup-id events_20250101_120000 \
  --sql "SELECT user_id, COUNT(*) FROM restore_input GROUP BY user_id" \
  --output table

For local queries, --backup-id accepts the backup name or path. The default table view is restore_input.

convert

Convert a backup into a different database engine (e.g. MySQL to PostgreSQL).

The convert command requires a Pro plan or higher.

coldplane convert [options]

Option	Required	Description
`--backup-id`	Yes	Backup ID to convert
`--to`	Yes	Target database connection string

Example:

coldplane convert \
  --backup-id bck_abc123 \
  --to "postgres://user:pass@host:5432/newdb"

analyze

Analyze database tables to find old data. Connects read-only to your database and reports how much data is older than a given threshold. No data leaves your machine. No account required.

Old data is not necessarily stale — you know your data best. Use the results to decide what to archive.

coldplane analyze [options]

Option	Required	Description
`--db-url`, `-d`	Yes	Database connection string (`postgres://` or `mysql://`)
`--tables`	*	Comma-separated list of tables to analyze
`--all`	*	Analyze all tables in the database
`--older-than`	No	Age threshold (default: `18m`). Supports `18m`, `1y`, `6m`, `90d`, `1y6m`
`--date-column`	No	Column to use for age detection (auto-detected if omitted)
`--json`	No	Output results as JSON

* Either --tables or --all is required.

Analyze specific tables:

coldplane analyze \
  --db-url "postgres://user:pass@host:5432/mydb" \
  --tables "orders,events"

Analyze all tables with custom threshold:

coldplane analyze \
  --db-url "mysql://user:pass@host:3306/mydb" \
  --all --older-than 1y

Override the date column:

coldplane analyze \
  --db-url "postgres://user:pass@host:5432/mydb" \
  --tables "users" \
  --date-column "last_login"

JSON output for CI/CD:

coldplane analyze \
  --db-url "postgres://user:pass@host:5432/mydb" \
  --all --json

The command prints a summary table with row counts, detected date columns, and estimated archive sizes. It ends with a copy-paste-ready backup create command including the --where clause to archive only the old data.

version

Print the CLI version and build information.

coldplane version

completion

Generate shell completion scripts.

coldplane completion [bash|zsh|fish|powershell]

On this page