CLI Reference

This page provides a complete reference of all pgbranch commands and their options.

Global Options

These options are available for all commands:

Option	Description
`--help`, `-h`	Show help for command
`--version`, `-v`	Show version

Commands Overview

Command	Description
`init`	Initialize pgbranch for a database
`branch`	List or create branches
`checkout`	Switch to a different branch
`delete`	Delete a branch
`status`	Show current branch and status
`log`	Show branch history
`diff`	Compare schemas between branches
`merge`	Merge schema changes
`hook`	Manage git hooks
`prune`	Remove stale branches
`remote`	Manage remote storage
`push`	Upload branch to remote
`pull`	Download branch from remote
`keys`	Manage encryption keys
`update`	Check for updates

init

Initialize pgbranch for a database in the current directory.

pgbranch init -d <database> [flags]

Flags

Flag	Short	Description	Default
`--database`	`-d`	Database name	(required)
`--host`	`-H`	PostgreSQL host	`localhost`
`--port`	`-p`	PostgreSQL port	`5432`
`--user`	`-U`	PostgreSQL user	`postgres`
`--password`	`-W`	Prompt for password	-

Examples

pgbranch init -d myapp_dev
pgbranch init -d myapp_dev -H localhost -p 5432 -U postgres -W

branch

List all branches or create a new branch.

pgbranch branch [name]

Arguments

Argument	Description
`name`	Name for new branch (optional)

Examples

pgbranch branch              # List branches
pgbranch branch main         # Create 'main' branch
pgbranch branch feature-api  # Create 'feature-api' branch

checkout

Switch to a different branch.

pgbranch checkout <branch>

Arguments

Argument	Description
`branch`	Branch to switch to (required)

Examples

pgbranch checkout main
pgbranch checkout feature-auth

delete

Delete a branch and its snapshot.

pgbranch delete <branch> [flags]

Alias: rm

Arguments

Argument	Description
`branch`	Branch to delete (required)

Flags

Flag	Short	Description	Default
`--force`	`-f`	Force delete current branch	`false`

Examples

pgbranch delete old-feature
pgbranch rm old-feature
pgbranch delete current-branch --force

status

Show current branch and repository status.

pgbranch status

Examples

pgbranch status
# Output:
# Database: myapp_dev (localhost:5432)
# Current branch: main
# Total branches: 5

log

Show branch history with details.

pgbranch log

Examples

pgbranch log
# Output:
# * main (current)
#     Created: 2024-01-15 10:30:00
#     Parent: -

diff

Compare schemas between branches.

pgbranch diff <branch1> [branch2] [flags]

Arguments

Argument	Description
`branch1`	First branch (required)
`branch2`	Second branch (default: working DB)

Flags

Flag	Description
`--stat`	Show summary statistics only
`--sql`	Show SQL statements

Examples

pgbranch diff main feature-auth
pgbranch diff main                    # Compare with working DB
pgbranch diff main feature-auth --stat
pgbranch diff main feature-auth --sql

merge

Merge schema changes between branches.

pgbranch merge <source> <target> [flags]

Arguments

Argument	Description
`source`	Branch with changes (required)
`target`	Branch to apply changes to (required)

Flags

Flag	Short	Description	Default
`--dry-run`	-	Preview without applying	`false`
`--migration-file`	-	Generate migration file	`false`
`--migration-dir`	-	Migration file directory	`migrations`
`--force`	`-f`	Skip confirmation	`false`

Examples

pgbranch merge feature-auth main
pgbranch merge feature-auth main --dry-run
pgbranch merge feature-auth main --migration-file
pgbranch merge feature-auth main --force

hook

Manage git hooks for automatic branch switching.

pgbranch hook <subcommand>

Subcommands

Subcommand	Description
`install`	Install git post-checkout hook
`uninstall`	Remove git hook

Examples

pgbranch hook install
pgbranch hook uninstall

prune

Remove branches not accessed recently.

pgbranch prune [flags]

Flags

Flag	Short	Description	Default
`--days`	`-d`	Days threshold for staleness	`7`
`--force`	`-y`	Skip confirmation	`false`

Examples

pgbranch prune              # Interactive, 7 days
pgbranch prune -d 14        # 14 days threshold
pgbranch prune -d 7 -y      # Auto-prune without confirmation

remote

Manage remote storage backends.

pgbranch remote <subcommand> [args] [flags]

Subcommands

Subcommand	Description
`add <name> <url>`	Add a new remote
`remove <name>`	Remove a remote (alias: `rm`)
`list`	List configured remotes (alias: `ls`)
`ls-remote`	List branches on remote
`set-default <name>`	Set default remote
`delete <branch>`	Delete branch from remote

Flags (add)

Flag	Description
`--no-credentials`	Skip credential prompts

Flags (ls-remote, delete)

Flag	Short	Description
`--remote`	`-r`	Specify remote name

Examples

pgbranch remote add origin s3://bucket/prefix
pgbranch remote add local /path/to/dir --no-credentials
pgbranch remote list
pgbranch remote remove origin
pgbranch remote set-default backup
pgbranch remote ls-remote
pgbranch remote ls-remote -r origin
pgbranch remote delete old-branch -r origin

push

Upload a branch to remote storage.

pgbranch push <branch> [flags]

Arguments

Argument	Description
`branch`	Branch to push (required)

Flags

Flag	Short	Description	Default
`--remote`	`-r`	Remote name	default
`--force`	`-f`	Overwrite if exists	`false`
`--description`	`-d`	Add description	-

Examples

pgbranch push main
pgbranch push main -r backup
pgbranch push main --force
pgbranch push main -d "Schema v2.1"

pull

Download a branch from remote storage.

pgbranch pull <branch> [flags]

Arguments

Argument	Description
`branch`	Branch to pull (required)

Flags

Flag	Short	Description	Default
`--remote`	`-r`	Remote name	default
`--as`	-	Local branch name	same
`--force`	`-f`	Overwrite local	`false`

Examples

pgbranch pull main
pgbranch pull main -r team
pgbranch pull main --as main-backup
pgbranch pull main --force

keys

Manage encryption keys for credentials.

pgbranch keys <subcommand> [flags]

Subcommands

Subcommand	Description
`generate`	Generate new encryption key
`status`	Show key status

Flags (generate)

Flag	Short	Description
`--force`	`-f`	Regenerate existing key

Examples

pgbranch keys status
pgbranch keys generate
pgbranch keys generate --force

update

Check for pgbranch updates.

pgbranch update

Examples

pgbranch update
# Output:
# Current version: v1.2.0
# Latest version: v1.3.0
# Run: go install github.com/le-vlad/pgbranch/cmd/pgbranch@latest

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments
`3`	Database connection error
`4`	Remote storage error

Environment Variables

pgbranch respects these environment variables:

Variable	Description
`PGHOST`	PostgreSQL host
`PGPORT`	PostgreSQL port
`PGUSER`	PostgreSQL user
`PGPASSWORD`	PostgreSQL password
`PGDATABASE`	PostgreSQL database
`AWS_ACCESS_KEY_ID`	AWS access key
`AWS_SECRET_ACCESS_KEY`	AWS secret key
`AWS_REGION`	AWS region
`AWS_ENDPOINT_URL`	Custom S3 endpoint