> For the complete documentation index, see [llms.txt](https://atomic-blend.gitbook.io/mongo2pg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atomic-blend.gitbook.io/mongo2pg/reference/cli-reference.md).

# CLI reference

```
mongo2pg schema plan [--out DIR] [--sample N]
mongo2pg schema apply [--allow-destructive]
mongo2pg schema down --to VERSION
mongo2pg schema version
mongo2pg snapshot [--collections a,b]
mongo2pg run
mongo2pg status
mongo2pg verify [--kind count,checksum,sample] [--collections a,b] [--sample N] [--buckets N] [--updated-at-column col]
mongo2pg cutover check [--updated-at-column col]
mongo2pg quarantine list [--collection c] [--reason r] [--limit N]
mongo2pg quarantine retry [--collection c]
mongo2pg quarantine export --out f.jsonl [--include-opaque]
mongo2pg reset --collection c --allow-destructive
mongo2pg healthcheck
mongo2pg version
```

Every command accepts the global flags below. This page mirrors `--help` — if the two ever disagree, trust the binary.

## Global flags

| Flag                  | Default | Meaning                                                                                                                                                                                                                                                          |
| --------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--config`            | —       | Path to the mapping YAML — resolution order source 1.                                                                                                                                                                                                            |
| `--configmap`         | —       | Kubernetes ConfigMap to read (and watch) as `<namespace>/<name>[#<key>]`.                                                                                                                                                                                        |
| `--allow-destructive` | `false` | Permit a change that drops a column, narrows a type, or erases data.                                                                                                                                                                                             |
| `--dry-run`           | `false` | Report what would be written without writing it. Runs the full mapping pipeline, including every coercion failure and unresolved reference, without touching PostgreSQL — the cheap way to validate a mapping against production data before the first real run. |
| `--log-format`        | `json`  | `json` \| `console`. Kubernetes leaves it at `json`; the Compose stack sets `console`.                                                                                                                                                                           |
| `--log-level`         | `info`  | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.                                                                                                                                                                                                     |
| `--metrics-addr`      | —       | Address to serve `/metrics`, `/healthz` and `/readyz` on. Empty disables the server.                                                                                                                                                                             |
| `--migrations-dir`    | —       | Directory of reviewed tern migration files. Empty applies the generated plan in memory instead.                                                                                                                                                                  |
| `--progress-interval` | `15s`   | How often a long-running command reports progress in the logs.                                                                                                                                                                                                   |

## `schema`

Plan, apply, roll back and inspect the generated PostgreSQL schema. See [The mapping file](/mongo2pg/concepts/concepts/mapping-file.md#schema-changes-and-the-destructive-gate) for the additive vs. destructive classification these commands enforce.

| Command                    | Flags                                                                                                                                                                                                                                                                                | Exit codes                                                                             |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `schema plan`              | `--out DIR` writes numbered `.sql` files instead of only printing the diff. `--sample N` (default `100`) is how many `_id` values per collection are sampled to detect an undeclared BSON binary subtype-3 encoding; `0` disables sampling and skips connecting to MongoDB entirely. | `0` clean, `3` destructive changes refused                                             |
| `schema apply`             | `--allow-destructive` (global) generates and applies destructive DDL too.                                                                                                                                                                                                            | `0`, `3`                                                                               |
| `schema down --to VERSION` | `--to` (required) is the mapping-schema tern version to roll back to.                                                                                                                                                                                                                | `0`, `1`                                                                               |
| `schema version`           | —                                                                                                                                                                                                                                                                                    | Prints both tern version tables (`schema_version_internal`, `schema_version_mapping`). |

## `snapshot`

Backfill only: applies the schema, then copies every existing document. Does not open a change-stream tail beyond what backfill itself requires.

| Flag                | Meaning                                                               |
| ------------------- | --------------------------------------------------------------------- |
| `--collections a,b` | Comma-separated subset to backfill. Default: every mapped collection. |

## `run`

Applies the schema, backfills, then streams changes forever — the container entrypoint, and the only command a Kubernetes Deployment or a Compose service normally runs. No collection-specific flags: `run` always drives every mapped collection through the full [phase machine](/mongo2pg/concepts/concepts/phases.md).

## `status`

Prints phase, lag, quarantine count and readiness for every collection as a one-shot table — the natural companion to `cutover check` for an operator who does not want to watch a log stream.

## `verify`

Compares both sides: counts, per-`_id`-range-bucket checksums, and re-mapped samples. See [What checks it performs](/mongo2pg/operating-a-migration/operations/verification-and-checks.md) for what each check kind actually does.

| Flag                           | Default                                      | Meaning                                                                  |
| ------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------ |
| `--kind count,checksum,sample` | all three                                    | Comma-separated subset of checks to run.                                 |
| `--collections a,b`            | all mapped collections                       | Subset to verify.                                                        |
| `--sample N`                   | package default (`100`)                      | Documents the sample check re-maps and diffs.                            |
| `--buckets N`                  | package default                              | `_id`-range buckets the checksum check compares.                         |
| `--updated-at-column col`      | derived from the mapping's `updatedAt` field | Override the column the checksum check hashes alongside the primary key. |

## `cutover check`

The deploy gate. Exits `0` only when every collection satisfies every condition in [What checks it performs](/mongo2pg/operating-a-migration/operations/verification-and-checks.md); otherwise exits `4` and prints exactly which condition failed, for which collection.

| Flag                      | Meaning                                                                        |
| ------------------------- | ------------------------------------------------------------------------------ |
| `--updated-at-column col` | Same override as `verify`, applied to the checks `cutover.requireVerify` runs. |

## `quarantine`

Work the list of documents that could not be mapped — see [Quarantine](/mongo2pg/concepts/concepts/quarantine.md) and [Handling quarantine](/mongo2pg/operating-a-migration/operations/handling-quarantine.md).

| Command             | Flags                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `quarantine list`   | `--collection c` (default: all), `--reason r` (substring match), `--limit N` (`0` = no limit)                                        |
| `quarantine retry`  | `--collection c` (default: all). Re-runs the current mapping against the current MongoDB state of every parked document.             |
| `quarantine export` | `--out f.jsonl` (required). `--include-opaque` includes the real value of fields marked `opaque` instead of a redaction placeholder. |

## `reset`

```bash
mongo2pg reset --collection tasks --allow-destructive
```

Erases one collection's migrated rows and mongo2pg's own state for it (`collection_state`, relevant `id_map`/`pending_fk`/`quarantine` rows), then backfills it from scratch. Destructive by construction, so `--allow-destructive` is required. The genuine use case is the same reason the PK namespace safety interlock exists — see [Namespace](/mongo2pg/concepts/concepts/primary-keys.md#namespace).

| Flag             | Meaning                                   |
| ---------------- | ----------------------------------------- |
| `--collection c` | Required. The single collection to reset. |

## `healthcheck`

Probes `/readyz` on `--metrics-addr` from inside the container. Exists because the image is distroless and has no `curl` or `wget` for a Docker `HEALTHCHECK` to call.

## `version`

Prints the build identity of this binary (version, commit).

## Exit codes

Exit codes are a contract an operator's deploy script can branch on, not merely a convention:

| Code | Name                    | Meaning                                                                                                                                 |
| ---- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `0`  | OK                      | The command did what it was asked to do.                                                                                                |
| `1`  | Runtime error           | Something failed while doing it — a connection, a query, a mapping error, a failed verification not otherwise classified below.         |
| `2`  | Usage / config error    | The invocation or the mapping is wrong. Nothing was attempted.                                                                          |
| `3`  | Destructive DDL refused | The command would have dropped a column, narrowed a type, or erased data, and `--allow-destructive` was not given. Nothing was changed. |
| `4`  | Cutover not ready       | `cutover check` ran to completion and the answer is no.                                                                                 |

An unclassified failure always returns `1`, never `0` — the codes are deliberately conservative about ever looking like success.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://atomic-blend.gitbook.io/mongo2pg/reference/cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.