CLI Module

The Click-based command-line entry point. The CLI Reference page is the user-facing reference; this page documents the importable Python surface.

iceberg_ops.cli

Command-line interface for iceberg-ops.

Exposes MigrationRunner commands as shell subcommands.

Usage

iceberg-ops init
iceberg-ops revision -m "create orders table"
iceberg-ops migrate                                     # settings from iceberg-ops.yaml
iceberg-ops --catalog sqlite --namespace sales status
iceberg-ops --catalog sqlite --namespace sales current   # alias of status
iceberg-ops --catalog sqlite --namespace sales migrate
iceberg-ops --catalog sqlite --namespace sales migrate --target 0002
iceberg-ops --catalog sqlite --namespace sales rollback --steps 1
iceberg-ops --catalog sqlite --namespace sales rollback --target 0001
iceberg-ops --catalog sqlite --namespace sales stamp
iceberg-ops --catalog sqlite --namespace sales stamp --target 0002
iceberg-ops --catalog sqlite --namespace sales history
iceberg-ops --catalog sqlite --namespace sales plan
iceberg-ops --catalog-name prod --namespace sales migrate

Configuration can also be loaded from a YAML file (default: iceberg-ops.yaml in the current directory). CLI flags override config file values. Relative paths in the config file (db_path, warehouse for sqlite, migrations_dir) resolve against the directory that holds the file; relative paths given as flags resolve against the current directory.

Catalog selection

--catalog sqlite keeps a local SQLite catalog, by default under local_data/ next to the config file (or in the current directory when there is no config file). --catalog-name NAME opens a catalog defined in .pyiceberg.yaml or PYICEBERG_CATALOG__<NAME>__* environment variables through pyiceberg.catalog.load_catalog(). --catalog glue|rest|hive|s3tables without a name loads the catalog named after the kind the same way, so PYICEBERG_CATALOG__REST__URI configures --catalog rest. A catalog flag replaces the config file’s catalog settings; the config’s db_path / warehouse only carry over when the flags select the same catalog as the config.

Errors

Usage errors exit with status 2; expected runtime failures (missing extra, missing table, catalog permission or commit errors, file system or connection errors) print one Error: line and exit with status 1. Set ICEBERG_OPS_TRACEBACK=1 to get the original traceback instead.

ASCII-only convention

Click renders the group-level --help before the group callback (and its _ensure_utf8_stdio() call) runs, so all option help=... strings, command docstrings, and group docstrings stick to ASCII. Subcommand --help renders after the group callback. Runtime click.echo / print inside command bodies may use UTF-8 since they execute after the encoding fix.