Reference

CLI reference

Every command and option, with defaults. Options can also be set in quarry.toml; a flag on the command line wins.

Usage

quarry <command> [options]

Global options

These work with every command.

Options for every command
Option	Default	Description
`--config <path>`	`quarry.toml`	Configuration file to read, relative to the current directory.
`--log-level <level>`	`info`	One of `error`, `warn`, `info` or `debug`.
`--json`	off	Print machine-readable JSON instead of text.
`--no-color`	off	Turn off coloured output. Also set by `NO_COLOR`.
`--help`	—	Show help for the command and exit.
`--version`	—	Print the version and exit.

Environment variables

Passwords are read from the environment and never from quarry.toml.

Environment variables
Variable	Used for
`QUARRY_SOURCE_PASSWORD`	Password for the source connection.
`QUARRY_TARGET_PASSWORD`	Password for the target connection.
`QUARRY_CONFIG`	Same as `--config`.
`NO_COLOR`	Same as `--no-color` when set to any value.

`quarry init`

Create quarry.toml in the current directory from two connection strings.

Usage

quarry init --source <url> --target <url> [options]

Options for quarry init
Option	Default	Description
`--source <url>`	Required	Connection string of the database to copy from.
`--target <url>`	Required	Connection string of the database to copy to.
`--tables <list>`	all tables	Comma-separated tables to include.
`--force`	off	Overwrite an existing `quarry.toml`.

`quarry plan`

Compare the source and target schemas and print what a run would copy. Writes nothing.

Usage

quarry plan [options]

Options for quarry plan
Option	Default	Description
`--tables <list>`	from config	Only plan these tables.
`--exclude <list>`	none	Leave these tables out.
`--ranges <n>`	auto	Split each large table into this many ranges.
`--output <file>`	none	Also write the plan to a file.

`quarry run`

Run a migration: plan, copy and catch-up, then keep replaying changes until quarry cutover.

Usage

quarry run [options]

Options for quarry run
Option	Default	Description
`--dry-run`	off	Check permissions, schema and disk, time a sample batch per table, and stop. A dry run changes nothing.
`--parallel <n>`	`4`	Copy workers. Each works on one range at a time.
`--batch-size <rows>`	`5000`	Rows per insert batch.
`--apply-workers <n>`	`2`	Workers that replay changes during catch-up.
`--resume`	off	Continue a stopped run from its last committed batch.
`--cutover <mode>`	`manual`	`manual` waits for `quarry cutover`; `auto` cuts over as soon as the lag is under `--max-lag`.
`--max-lag <duration>`	`1s`	Lag at which an automatic cut-over may start.

`quarry status`

Show the phase, progress and replication lag of the migration in the current directory.

Terminal

$ quarry status
shop · catch-up
  copied   72,423,100 of 72,423,100 rows (100%)
  lag      340 ms
  started  12 September 2026, 14:02 UTC

Options for quarry status
Option	Default	Description
`--watch`	off	Refresh every 2 seconds until interrupted.
`--verbose`	off	Also list workers and open transactions on the source.

`quarry cutover`

Switch writes from the source to the target.

Usage

quarry cutover [options]

Options for quarry cutover
Option	Default	Description
`--timeout <duration>`	`30s`	How long to wait for the lag to reach zero before giving up.
`--hook <command>`	from config	Command that points your application at the target.
`--keep-reverse <duration>`	`24h`	How long to replicate target writes back to the source.
`--yes`	off	Skip the confirmation prompt.

`quarry rollback`

Undo a migration. Before cut-over it removes what Quarry created on the target; after cut-over it switches writes back to the source, as long as reverse replication is still running.

Usage

quarry rollback [options]

Options for quarry rollback
Option	Default	Description
`--keep-target`	off	Before cut-over: keep the copied tables on the target.
`--hook <command>`	from config	After cut-over: command that points your application back at the source.
`--yes`	off	Skip the confirmation prompt.

`quarry verify`

Compare the source and target table by table: row counts, and checksums of a sample of rows.

Usage

quarry verify [options]

Options for quarry verify
Option	Default	Description
`--tables <list>`	all planned	Only verify these tables.
`--sample <percent>`	`1`	Share of rows to checksum, from 0 to 100.
`--full`	off	Checksum every row. Slow on large tables.

Exit codes

Every command exits with one of these codes, so scripts can tell a failed cut-over from a bad flag.

Exit codes
Code	Meaning
`0`	Success.
`1`	The command failed; the error is printed.
`2`	Invalid option or configuration.
`3`	A dry run found errors.
`4`	Cut-over timed out; the source is writable again.
`5`	`quarry verify` found differences.