guepard-corp/gfs/use-gfs-cli

Name: use-gfs-cli
Author: guepard-corp

Claude Code and agent skill by guepard-corp/gfs

Trust tier 2

community

LLM review pending

Source check pending

Checking that the SKILL.md file is still in the repository.

Git-like version control for databases using the GFS CLI. Manage database states with commits, branches, time travel, and schema versioning.

Install

npx vskill@latest install guepard-corp/gfs/use-gfs-cli

SKILL.md

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

shell

gfs version

2. If not installed, install using

bash

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

Validate the installation:

shell

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:

shell

# 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

shell

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
`gfs fsck`	0	Repository consistent, nothing unreachable
`gfs fsck`	1	Unreachable objects found (collectable)
`gfs fsck`	2	Corruption found: something referenced is missing, or an object could not be identified
`gfs fsck`	3	The check could NOT be completed — says nothing about the repository. Handle this before 1 or 2: an unreadable object, a `refs/heads` entry that could not be read or is absent, or a Kubernetes backend with no reachable cluster all land here, and on a cluster-backed repository with no cluster it is the ordinary answer
any command	3	A usage error — an unknown flag, a value that will not parse, a missing subcommand, including bare `gfs config`. The command did not run, so nothing it printed describes your repository. Check your own arguments before investigating: a mistyped flag produces the same `3` as an unreachable cluster
any command	0	`--help` and `--version` are requests, not errors

A ref whose value is present but will not parse — empty, or not a hash — is 2, not 3. A file that could not be read is a hole; a file that reads back as nonsense is corruption, and only the second says something about the repository.

Use exit codes for conditional logic:

shell

if gfs status > /dev/null 2>&1; then
    gfs query "SELECT 1"
else
    gfs compute start
fi

Quick Start

1. Check available database providers

shell

gfs providers

This shows all supported database providers, versions, and features.

2. Initialize a repository

First, ask the user which database provider and version they need. Then initialize:

shell

# For PostgreSQL
gfs init --database-provider postgres --database-version 17
 
# For MySQL
gfs init --database-provider mysql --database-version 8.0

This creates a .gfs directory in your project and, for a container-backed provider, starts a container with the database.

SQLite starts nothing — it is a file this process opens:

shell

gfs init --database-provider sqlite --database-version 3

3. Check status

shell

gfs status

Shows the current branch, the HEAD commit, the active workspace, and database container status (including the connection string when there is one). For an embedded provider there is no container section, and the connection string is a sqlite: URL to the file.

The MCP status tool reports the same fields from the same source, so the two surfaces cannot disagree.

Revision References

GFS supports Git-style revision notation for referencing commits:

Basic Formats

HEAD - Current commit
main - Branch tip (any branch name)
abc123def456... - Full commit hash (64 characters)

Tilde Notation (Ancestor References)

Reference ancestor commits using ~ notation:

HEAD~1 - Parent of HEAD (previous commit)
HEAD~5 - 5th ancestor of HEAD
main~3 - 3 commits before main branch tip
abc123~2 - 2nd parent of commit abc123
HEAD~ - Same as HEAD~1 (defaults to 1)

Usage Examples

shell

# Checkout previous commit
gfs checkout HEAD~1
 
# Compare schema with 5 commits ago
gfs schema diff HEAD~5 HEAD
 
# View schema from 3 commits back
gfs schema show main~3
 
# Show specific ancestor
gfs schema show abc123def456...~2
 
# View log from ancestor to current
gfs log --from HEAD~10 --until HEAD

Tilde notation works with any command that accepts commit references: checkout, schema show, schema diff, log, etc.

Core Workflow

Best Practices

CRITICAL: Always commit before making mutations to the database. This enables rollback if issues occur.

shell

gfs commit -m "before adding new feature"

1. Commit Changes

Create snapshots of your database state (automatically includes schema):

shell

gfs commit -m "descriptive message"
 
# With author information
gfs commit -m "added user table" --author "John Doe" --author-email "john@example.com"

New in schema versioning: Every commit automatically captures the database schema at commit time. This includes both structured metadata (tables, columns, types) and native DDL (SQL).

2. View History

shell

# View all commits
gfs log
 
# Limit number of commits
gfs log --max-count 10
 
# View commits in a range
gfs log --from main --until feature-branch
 
# Show branch topology graph (all branches)
gfs log --graph --all
 
# Show graph for current branch only
gfs log --graph

3. Manage Branches

shell

# List all branches (* marks current)
gfs branch
 
# Create branch at HEAD (without switching)
gfs branch feature-branch
 
# Create branch from specific commit/checkpoint
gfs branch release/v1.0 <commit_id>
 
# Create and switch to new branch
gfs branch -c feature-branch
# or the classic shorthand:
gfs checkout -b feature-branch
 
# Delete a branch
gfs branch -d feature-branch

4. Switch Branches

shell

# Switch to existing branch
gfs checkout main
 
# Checkout specific commit (use full 64-char hash from gfs log)
gfs checkout <commit_id>

5. Database Management

Start/Stop Database Container

Container-backed providers only. On a SQLite repository every gfs compute action reports that an embedded database is a file this process opens, with no container to start, stop or inspect — and gfs user likewise reports that there is no server, so no roles, passwords or privileges to manage.

shell

# Check container status
gfs compute status
 
# Start the database
gfs compute start
 
# Stop the database
gfs compute stop
 
# Restart the database
gfs compute restart
 
# Pause/Unpause (keeps state in memory)
gfs compute pause
gfs compute unpause
 
# View logs
gfs compute logs
gfs compute logs --tail 100
gfs compute logs --since "2024-01-01T00:00:00Z"

6. Query Database

Execute SQL queries directly:

shell

# Interactive mode (opens database client)
gfs query
 
# Execute a query
gfs query "SELECT * FROM users;"
 
# Query specific database
gfs query --database mydb "SHOW TABLES;"

7. Schema Operations

NEW: GFS now provides comprehensive schema versioning and inspection capabilities.

Extract Current Schema

Extract schema from the running database:

shell

# Extract and display schema (JSON metadata)
gfs schema extract
 
# Save to file
gfs schema extract --output schema.json
 
# Compact JSON output
gfs schema extract --compact

Show Schema from Commit

View the schema as it existed at any commit:

shell

# Show full schema (metadata + DDL) from HEAD
gfs schema show HEAD
 
# Show schema from specific commit
gfs schema show abc123
 
# Show only metadata (JSON)
gfs schema show HEAD --metadata-only
 
# Show only DDL (SQL)
gfs schema show main --ddl-only

Output includes:

Schema hash (content-addressed identifier)
Database driver and version
Structured metadata (schemas, tables, columns)
Native DDL dump (CREATE TABLE statements, etc.)

Compare Schemas Between Commits

Track schema evolution by comparing commits. Both arguments accept rev~n notation for ancestor references:

shell

# Compare HEAD with previous commit
gfs schema diff HEAD~1 HEAD
 
# Compare with 5 commits ago using rev~n notation
gfs schema diff HEAD~5 HEAD
 
# Compare two branches
gfs schema diff main feature-branch
 
# Compare specific commits (rev~n works with any commit reference)
gfs schema diff abc123~2 def456

Diff output includes:

Schema hash comparison (detects if schemas are identical)
Table count changes (+/- tables)
Column count changes (+/- columns)
DDL comparison summary
Suggestion to use external diff tools for detailed DDL differences

Schema Versioning Features

Automatic Capture: Every gfs commit automatically extracts and stores the schema
Content-Addressed: Identical schemas share the same hash (storage deduplication)
Dual Format: Both JSON metadata and SQL DDL are stored
Time Travel: View schema at any point in history
Non-Blocking: Schema extraction failures don't prevent commits
Backward Compatible: Old commits without schemas work fine

8. Import/Export Data

Export

shell

# Export as SQL dump
gfs export --format sql
 
# Export to specific directory
# --output-dir must be inside the repository; omit it to use the default
gfs export --format sql --output-dir ./exports
 
# Export using custom format (PostgreSQL's pg_dump custom format)
gfs export --format custom

Import

shell

# Import data file (format auto-detected from extension)
gfs import --file /path/to/data.sql
 
# Specify format explicitly
gfs import --format sql --file /path/to/dump.sql
gfs import --format csv --file /path/to/data.csv
gfs import --format json --file /path/to/data.json
 
# Import custom database-specific format (e.g., PostgreSQL's pg_dump custom format)
gfs import --format custom --file /path/to/dump.dump

Supported formats: SQL, CSV, JSON, custom (database-specific formats)

Configuration

GFS stores configuration in .gfs/config.toml:

shell

# Read one configuration value. A key is required — bare `gfs config` exits 3.
# Supported keys: user.name, user.email, storage.compression, storage.reflink,
# telemetry.enabled
gfs config user.name
 
# Configuration includes:
# - Database provider and version
# - Container runtime settings
# - Branch information

Common Workflows

Experiment with Schema Changes

shell

# 1. Create a branch for experimentation
gfs checkout -b schema-experiment
 
# 2. Make schema changes (via gfs query or your DB client)
gfs query "ALTER TABLE users ADD COLUMN age INTEGER;"
 
# 3. Test the changes
gfs query "SELECT * FROM users;"
 
# 4. If satisfied, commit (schema is automatically captured)
gfs commit -m "added age column to users"

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/use-gfs-cli/SKILL.md

Popularity

Repository stars: 150
Repository forks: 13
7-day trend score: 25

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/guepard-corp/gfs/use-gfs-cli/badge)](https://verified-skill.com/skills/guepard-corp/gfs/use-gfs-cli)

Something wrong with this skill or its page? Tell us.

Install

SKILL.md

GFS CLI (Git For database Systems)

Supported Databases

Installation

1. Check if GFS is installed

2. If not installed, install using

Global Flags

--json — Machine-Readable Output

--color — Color Control

Exit Codes

Quick Start

1. Check available database providers

2. Initialize a repository

3. Check status

Revision References

Basic Formats

Tilde Notation (Ancestor References)

Usage Examples

Core Workflow

Best Practices

1. Commit Changes

2. View History

3. Manage Branches

4. Switch Branches

5. Database Management

Start/Stop Database Container

6. Query Database

7. Schema Operations

Extract Current Schema

Show Schema from Commit

Compare Schemas Between Commits

Schema Versioning Features

8. Import/Export Data

Export

Import

Configuration

Common Workflows

Experiment with Schema Changes

Security

Quality evaluation

Source

Popularity

Works with

`--json` — Machine-Readable Output

`--color` — Color Control