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`)

Example:

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

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

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>

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 (`SELECT *` is not allowed; specify explicit columns)
`--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`)

Example:

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

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"

version

Print the CLI version and build information.

coldplane version

completion

Generate shell completion scripts.

coldplane completion [bash|zsh|fish|powershell]

On this page