CLI Reference

Complete reference for the epoch command-line interface.

Global Options

Option	Description
`-C, --directory <PATH>`	Run as if started in PATH
`--format <FORMAT>`	Output format: `text`, `json`
`-q, --quiet`	Suppress non-essential output
`-v, --verbose`	Enable verbose output
`--config <FILE>`	Path to config file
`--version`	Show version
`--help`	Show help

Commands

epoch init

Initialize a new repository.

epoch init <NAME> [OPTIONS]

Arguments:

<NAME> - Repository name (required)

Options:

-d, --description <DESC> - Repository description
-b, --default-branch <BRANCH> - Default branch name (default: main)
--metadata-url <URL> - Metadata database URL

Examples:

epoch init my-repo
epoch init my-repo --description "Production data"
epoch init my-repo --metadata-url "postgresql://localhost/horizon_epoch"

epoch branch

Manage branches.

epoch branch [SUBCOMMAND]

Subcommands:

epoch branch list

List all branches.

epoch branch list
epoch branch list --format json

epoch branch create

Create a new branch.

epoch branch create <NAME> [--from <SOURCE>]

Options:

--from <SOURCE> - Source branch (default: current branch)

Examples:

epoch branch create feature-x
epoch branch create hotfix --from production

epoch branch delete

Delete a branch.

epoch branch delete <NAME> [--force]

Options:

-f, --force - Force delete even if unmerged

epoch checkout

Switch to a branch.

epoch checkout <BRANCH>

Examples:

epoch checkout main
epoch checkout feature/new-schema

epoch commit

Create a new commit.

epoch commit -m <MESSAGE> [OPTIONS]

Options:

-m, --message <MSG> - Commit message (required)
-a, --all - Commit all changed tables
--tables <TABLES> - Comma-separated list of tables to commit
--author <NAME> - Override author name
--email <EMAIL> - Override author email

Examples:

epoch commit -m "Add user preferences"
epoch commit -m "Update orders" --tables orders,order_items

epoch merge

Merge a branch into current branch.

epoch merge <BRANCH> [OPTIONS]

Options:

--strategy <STRATEGY> - Merge strategy: default, ours, theirs
--no-commit - Merge but don’t commit
--message <MSG> - Custom merge commit message
--continue - Continue after conflict resolution
--abort - Abort in-progress merge

Examples:

epoch merge feature/updates
epoch merge feature/updates --strategy theirs
epoch merge --continue
epoch merge --abort

epoch diff

Show differences between branches or commits.

epoch diff [SOURCE] [TARGET] [OPTIONS]

Arguments:

<SOURCE> - Source branch/commit (default: HEAD)
<TARGET> - Target branch/commit

Options:

--table <TABLE> - Show diff for specific table
--stat - Show statistics only
--name-only - Show only changed table names

Examples:

epoch diff                           # Uncommitted changes
epoch diff main                      # Current branch vs main
epoch diff main feature/updates      # Between two branches
epoch diff abc123f def456g           # Between commits
epoch diff --stat                    # Summary only

epoch log

Show commit history.

epoch log [OPTIONS]

Options:

-n, --max-count <N> - Limit output to N commits
--oneline - One line per commit
--since <DATE> - Show commits since date
--until <DATE> - Show commits until date
--author <PATTERN> - Filter by author
--table <TABLE> - Show commits affecting table

Examples:

epoch log
epoch log --oneline -10
epoch log --since "2024-01-01"
epoch log --table users

epoch status

Show working tree status.

epoch status [OPTIONS]

Options:

--short - Short format
--porcelain - Machine-readable format

Examples:

epoch status
epoch status --short

epoch table

Manage tables.

epoch table [SUBCOMMAND]

epoch table add

epoch table add <NAME> --location <LOCATION> [OPTIONS]

Options:

--location <URL> - Table location (required)
--primary-key <COLS> - Primary key columns
--storage <NAME> - Storage backend name (alternative to location URL)

Location Formats by Backend:

Backend	Format	Example
PostgreSQL	`postgresql://[user:pass@]host[:port]/database/schema.table`	`postgresql://localhost/mydb/public.users`
MySQL	`mysql://[user:pass@]host[:port]/database/table`	`mysql://localhost/analytics/events`
SQL Server	`mssql://[user:pass@]host[:port]/database/schema.table`	`mssql://sqlserver/warehouse/dbo.orders`
SQLite	`sqlite:///path/to/file.db/table`	`sqlite:///data/local.db/users`
S3	`s3://bucket/prefix/path`	`s3://datalake/delta/events`
Azure Blob	`azure://account/container/prefix`	`azure://myaccount/data/tables/users`
GCS	`gs://bucket/prefix/path`	`gs://my-bucket/delta/products`
Local	`file:///path/to/directory`	`file:///data/parquet/users`

Examples:

# PostgreSQL
epoch table add users --location "postgresql://localhost/mydb/public.users" \
    --primary-key id

# MySQL
epoch table add orders --location "mysql://mysql-host/shop/orders" \
    --primary-key order_id

# SQL Server
epoch table add inventory --location "mssql://sqlserver/warehouse/dbo.inventory" \
    --primary-key sku

# SQLite
epoch table add config --location "sqlite:///data/app.db/config" \
    --primary-key key

# S3/Delta Lake
epoch table add events --location "s3://datalake/delta/events" \
    --primary-key event_id

# Azure Blob
epoch table add telemetry --location "azure://myaccount/data/telemetry" \
    --primary-key id

# GCS
epoch table add products --location "gs://my-bucket/delta/products" \
    --primary-key product_id

# Local filesystem
epoch table add local_data --location "file:///data/parquet/sales" \
    --primary-key transaction_id

# Using storage backend name (when storage is already registered)
epoch table add users --storage prod-pg --primary-key id

epoch table list

List registered tables.

epoch table list [--format json]

epoch table remove

Unregister a table.

epoch table remove <NAME> [--force]

epoch tag

Manage tags.

epoch tag [SUBCOMMAND]

epoch tag create

Create a tag.

epoch tag <NAME> [COMMIT] [OPTIONS]

Options:

-m, --message <MSG> - Tag message

Examples:

epoch tag v1.0.0
epoch tag v1.0.0 abc123f -m "Release 1.0.0"

List all tags.

epoch tag list

epoch tag delete

Delete a tag.

epoch tag delete <NAME>

epoch reset

Reset current branch to a commit.

epoch reset [OPTIONS] <COMMIT>

Options:

--soft - Keep changes staged
--hard - Discard all changes

Examples:

epoch reset --soft HEAD~1
epoch reset --hard v1.0.0

epoch revert

Create a commit that undoes a previous commit.

epoch revert <COMMIT> [OPTIONS]

Options:

--no-commit - Revert but don’t commit

Examples:

epoch revert abc123f
epoch revert HEAD

epoch stash

Stash uncommitted changes.

epoch stash [SUBCOMMAND]

epoch stash push

Save changes to stash.

epoch stash push [-m <MESSAGE>]

epoch stash pop

Apply and remove latest stash.

epoch stash pop [<STASH>]

epoch stash list

List stashes.

epoch stash list

epoch storage

Manage storage backends.

epoch storage [SUBCOMMAND]

epoch storage add

epoch storage add <NAME> --type <TYPE> [OPTIONS]

Arguments:

<NAME> - Unique name for the storage backend (required)

Options:

--type <TYPE> - Backend type (required): postgresql, mysql, mssql, sqlite, s3, azureblob, gcs, local
--description <DESC> - Optional description
--set-default - Set as the default storage backend

PostgreSQL/MySQL/MSSQL Options:

--host <HOST> - Database host (required)
--port <PORT> - Database port (PostgreSQL: 5432, MySQL: 3306, MSSQL: 1433)
--database <DB> - Database name (required)
--schema <SCHEMA> - Schema name (PostgreSQL only)
--username <USER> - Username
--ssl-mode <MODE> - SSL mode

SQLite Options:

--database <PATH> - Database file path (required)

S3 Options:

--bucket <BUCKET> - Bucket name (required)
--region <REGION> - AWS region
--endpoint <URL> - Custom endpoint (for MinIO, etc.)
--path-prefix <PREFIX> - Key prefix
--path-style - Use path-style URLs

Azure Blob Options:

--account <ACCOUNT> - Storage account name (required)
--container <CONTAINER> - Container name (required)
--path-prefix <PREFIX> - Blob prefix

GCS Options:

--bucket <BUCKET> - Bucket name (required)
--project <PROJECT> - GCP project ID
--path-prefix <PREFIX> - Object prefix

Local Filesystem Options:

--base-path <PATH> - Base directory path (required)

Credential Options:

--credentials <TYPE> - Credential resolution: environment, aws-profile, gcp-service-account, azure-managed-identity, vault
--profile <NAME> - AWS profile name (with aws-profile)
--key-file <PATH> - GCP service account key file (with gcp-service-account)
--client-id <ID> - Azure client ID (with azure-managed-identity)
--vault-path <PATH> - Vault secret path (with vault)
--vault-role <ROLE> - Vault role name (with vault)

Examples:

# PostgreSQL
epoch storage add prod-pg --type postgresql \
    --host db.example.com --database production

# MySQL
epoch storage add analytics-mysql --type mysql \
    --host mysql.example.com --port 3306 --database analytics

# SQL Server
epoch storage add warehouse-mssql --type mssql \
    --host sqlserver.example.com --database warehouse

# SQLite
epoch storage add local-sqlite --type sqlite --database ./data/local.db

# S3
epoch storage add datalake --type s3 \
    --bucket company-datalake --region us-west-2

# S3-compatible (MinIO)
epoch storage add dev-minio --type s3 \
    --bucket local-data --endpoint http://localhost:9000 --path-style

# Azure Blob
epoch storage add azure-store --type azureblob \
    --account myaccount --container data

# GCS
epoch storage add gcs-store --type gcs \
    --bucket my-bucket --project my-project

# Local Filesystem
epoch storage add local-fs --type local --base-path /data/epoch

# With credentials
epoch storage add prod-s3 --type s3 --bucket prod-data \
    --credentials aws-profile --profile production

epoch storage list

List configured storage backends.

epoch storage list [--type <TYPE>] [--format json]

Options:

--type <TYPE> - Filter by backend type

epoch storage show

Show detailed information about a storage backend.

epoch storage show <NAME>

epoch storage update

Update a storage backend configuration.

epoch storage update <NAME> [OPTIONS]

Options:

--description <DESC> - Update description
--disable - Disable the backend
--enable - Enable the backend

epoch storage remove

Remove a storage backend.

epoch storage remove <NAME> [--force]

epoch storage default

Manage the default storage backend.

epoch storage default set <NAME>   # Set default
epoch storage default show         # Show current default
epoch storage default clear        # Clear default

epoch storage test-credentials

Test credential provider for a storage backend.

epoch storage test-credentials <NAME>
epoch storage test-credentials --all

epoch storage credentials

Show credential status for storage backends.

epoch storage credentials <NAME>
epoch storage credentials --all

epoch storage tunnels

Show SSH tunnel status for storage backends.

epoch storage tunnels [NAME]

Schema Commands

epoch schema show

Display schema for a table at a specific commit or branch.

epoch schema show <TABLE> [OPTIONS]

Arguments:

<TABLE> - Table name (required)

Options:

--at <REF> - Show schema at specific commit, branch, or tag
--live - Show live database schema (not stored snapshot)
--generate-ddl - Output as PostgreSQL DDL
--format <FORMAT> - Output format: text, json

Examples:

# Show current schema
epoch schema show users

# Show schema at specific commit
epoch schema show users --at abc123f

# Show schema on a branch
epoch schema show users --at feature/new-fields

# Compare with live database
epoch schema show users --live

# Generate DDL from schema
epoch schema show users --generate-ddl

epoch schema diff

Compare schemas between two refs and optionally generate migration DDL.

epoch schema diff <TABLE> <SOURCE> <TARGET> [OPTIONS]

Arguments:

<TABLE> - Table name (required)
<SOURCE> - Source ref (branch, commit, or tag)
<TARGET> - Target ref (branch, commit, or tag)

Options:

--show-ddl - Show DDL migration statements
--ddl-output <FILE> - Write DDL to file
--format <FORMAT> - Output format: text, json, flyway, liquibase
--columns-only - Show only column changes
--constraints-only - Show only constraint changes
--indexes-only - Show only index changes

Examples:

# Compare schemas between branches
epoch schema diff users main feature/updates

# Generate migration DDL
epoch schema diff users main feature/updates --show-ddl

# Write DDL to file
epoch schema diff users main feature/updates --ddl-output migrations/V2.sql

# Generate Flyway-compatible migration
epoch schema diff users main feature/updates --format flyway --ddl-output db/migration/V2__update_users.sql

epoch schema apply

Apply schema changes from a ref to the live database.

epoch schema apply <TABLE> --from <REF> [OPTIONS]

Arguments:

<TABLE> - Table name (required)

Options:

--from <REF> - Source ref with desired schema (required)
--dry-run - Show what would be executed without applying
--force - Allow destructive operations
--online - Use CONCURRENTLY for index operations
--lock-timeout <DURATION> - Lock timeout (default: 30s)
--statement-timeout <DURATION> - Statement timeout (default: 5m)
--retries <N> - Number of retries on failure (default: 3)
--no-transaction - Run statements individually (required for CONCURRENTLY)

Examples:

# Preview changes (dry-run)
epoch schema apply users --from feature/updates --dry-run

# Apply schema changes
epoch schema apply users --from feature/updates

# Apply with online mode for large tables
epoch schema apply users --from feature/updates --online

# Apply with custom timeouts
epoch schema apply users --from feature/updates \
    --lock-timeout 10s \
    --statement-timeout 10m

# Force destructive changes (after backup)
epoch schema apply users --from feature/updates --force

epoch schema status

Show schema drift status for tables.

epoch schema status [TABLES...] [OPTIONS]

Arguments:

[TABLES...] - Specific tables to check (optional, all if omitted)

Options:

--check-bloat - Also check table bloat
--check-indexes - Check index validity
--format <FORMAT> - Output format: text, json

Examples:

# Check all tables
epoch schema status

# Check specific tables
epoch schema status users orders

# Check with bloat analysis
epoch schema status --check-bloat

# JSON output for automation
epoch schema status --format json

Output:

Table      | Latest Schema | Historical | Live DB  | Status
-----------|---------------|------------|----------|--------
users      | Yes           | Yes        | Synced   | OK
orders     | Yes           | Partial    | Synced   | OK
products   | Yes           | No         | Drifted  | Needs sync
events     | No            | No         | N/A      | S3 table

epoch migrate-schemas

Backfill schema data for existing commits.

epoch migrate-schemas [OPTIONS]

Options:

--backfill - Backfill missing schemas from live database
--all - Process all tables
--table <TABLE> - Process specific table
--since <DATE> - Only backfill commits since date
--skip-inaccessible - Skip tables that can’t be introspected
--import-from <TOOL> - Import from external tool (flyway, liquibase)
--dry-run - Show what would be done

Examples:

# Backfill all tables (dry-run)
epoch migrate-schemas --backfill --all --dry-run

# Backfill specific table
epoch migrate-schemas --backfill --table users

# Backfill since a date
epoch migrate-schemas --backfill --all --since "2024-01-01"

# Import from Flyway migrations
epoch migrate-schemas --import-from flyway ./db/migration

epoch conflicts

Manage merge conflicts.

epoch conflicts [SUBCOMMAND]

epoch conflicts show

Show current conflicts.

epoch conflicts show [--format json]

epoch conflicts resolve

Resolve conflicts.

epoch conflicts resolve [OPTIONS]

Options:

--interactive - Interactive resolution
--ours - Accept our version
--theirs - Accept their version
--table <TABLE> - Resolve specific table
--record <ID> - Resolve specific record
--field <FIELD> - Resolve specific field
--value <VALUE> - Set specific value

epoch query

Run a query against the repository.

epoch query <SQL> [OPTIONS]

Options:

--branch <BRANCH> - Query specific branch
--at <REF> - Query at commit/tag/time
--format <FMT> - Output format: table, json, csv

Examples:

epoch query "SELECT * FROM users"
epoch query "SELECT COUNT(*) FROM orders" --branch staging
epoch query "SELECT * FROM users" --at v1.0.0 --format json

epoch local

Manage local development environment.

epoch local [SUBCOMMAND]

epoch local start

Start local services.

epoch local start

epoch local stop

Stop local services.

epoch local stop

epoch local status

Show local service status.

epoch local status

Configuration File

~/.epoch/config.toml:

[defaults]
format = "text"
author_name = "Your Name"
author_email = "you@example.com"

[metadata]
url = "postgresql://localhost/horizon_epoch"

Environment Variables

Variable	Description
`EPOCH_METADATA_URL`	Metadata database URL
`EPOCH_CONFIG_FILE`	Config file path
`EPOCH_LOG_LEVEL`	Log level (debug, info, warn, error)
`EPOCH_FORMAT`	Default output format

Keyboard shortcuts

Horizon Epoch Documentation