use-gfs-cli

GFS CLI (Git For database Systems)

GFS brings Git-like version control to your databases. Commit database states, create branches, switch between versions, travel through your database history, and track schema evolution over time.

Supported Databases

• PostgreSQL (versions 13-18)
• MySQL (versions 8.0-8.1)
• SQLite (version 3) — file-based; needs no container runtime

Installation

1. Check if GFS is installed

gfs version

2. If not installed, install using

curl -fsSL https://gfs.guepard.run/install | bash

Validate the installation:

gfs version

Global Flags

--json — Machine-Readable Output

Add --json before any subcommand for structured JSON output instead of styled text. This is the recommended approach for scripts and AI agents:

# Commit and get the hash programmatically
gfs --json commit -m "add users table"
# → {"hash":"b57732d8...","branch":"main","message":"add users table"}

# Init and get the connection string
gfs --json init --database-provider postgres --database-version 17
# → {"path":"/my/project","branch":"main","config":".gfs/config.toml","provider":"postgres"}

# Checkout and confirm
gfs --json checkout -b feature/auth
# → {"hash":"b57732d8...","branch":"feature/auth","new_branch":true}

# Export and get the file path
gfs --json export --format sql
# → {"file_path":".gfs/exports/dump.sql","format":"sql"}

Supported commands: init, commit, checkout, export, import

Status JSON:

• gfs --json status outputs JSON by default
• gfs status --output json outputs JSON (explicit format)
• gfs status --output table forces table output (overrides global --json)

--color — Color Control

gfs --color never status   # No ANSI colors (for piping)
gfs --color always log     # Force colors even when piped

Exit Codes

Command	Code	Meaning
gfs status	0	Compute running or not configured
gfs status	1	Compute configured but not running
gfs schema diff	0	No schema changes
gfs schema diff	1	Schema changes detected
gfs schema diff	2	Breaking changes detected