Seedfast CLI

AI-powered PostgreSQL database seeding tool

Seedfast CLI generates realistic test data for PostgreSQL databases. It connects to a backend service that uses AI to understand your database schema and create meaningful, contextually appropriate seed data.

Features

• AI-Powered Planning: Automatically analyzes your database schema and generates an intelligent seeding plan
• Realistic Data: Creates contextually appropriate test data based on table relationships and constraints
• Interactive UI: Rich terminal interface with real-time progress tracking
• Concurrent Execution: Multi-worker architecture for fast data generation
• Secure Authentication: OAuth-style device flow with OS-level credential storage
• Schema-Aware: Respects foreign keys, constraints, and relationships between tables

Installation

npm (Node.js/JavaScript projects)

# Global installation
npm install -g seedfast

# Or use with npx (no installation required)
npx seedfast seed

Homebrew (macOS and Linux)

brew install argon-it/tap/seedfast

Download Binary

Download the latest release for your platform from the releases page.

From Source

Requires Go 1.25+:

git clone <repository-url>
cd cli
go build -o seedfast

Quick Start

1. Authenticate

seedfast login

Opens your browser for authentication. The CLI waits until you complete the login.

2. Connect to Database

seedfast connect

Enter your PostgreSQL connection string:

postgres://user:password@localhost:5432/dbname?sslmode=disable

3. Seed Your Database

seedfast seed

The CLI will:

1. Analyze your database schema
2. Present a seeding plan for your approval
3. Generate and insert realistic test data
4. Show real-time progress for each table

Commands

seedfast login      # Authenticate with the backend service
seedfast connect    # Configure database connection
seedfast seed       # Start the seeding process
seedfast me         # Check authentication status (formerly whoami)
seedfast logout     # Clear stored credentials
seedfast --version  # Show version information

CI/CD Integration

For automated database seeding in CI/CD pipelines, use API key authentication with the --scope flag:

export SEEDFAST_API_KEY=sfk_live_your_api_key_here
seedfast seed --scope "test database" --output json

GitHub Actions Example:

- name: Seed Database
  env:
    SEEDFAST_API_KEY: ${{ secrets.SEEDFAST_API_KEY }}
  run: |
    curl -L https://cli.seedfa.st/install.sh | sh
    seedfast seed --scope "development database" --output json

For complete CI/CD integration guide with examples for GitHub Actions, GitLab CI, CircleCI, and Jenkins, see docs/cicd/README.md.

Configuration

Environment Variables

• SEEDFAST_DSN - PostgreSQL connection string (overrides stored value)
• DATABASE_URL - Alternative PostgreSQL connection string (fallback)
• SEEDFAST_VERBOSE - Enable verbose logging (1 to enable)

Database Connection

You can configure the database connection in three ways (in order of priority):

1. Environment variable SEEDFAST_DSN
2. Environment variable DATABASE_URL
3. Stored value from seedfast connect command (saved in OS keychain)

How It Works

1. Authentication: OAuth-style device flow securely authenticates with the backend
2. Schema Analysis: Backend analyzes your PostgreSQL schema (tables, relationships, constraints)
3. AI Planning: AI planner determines optimal seeding strategy and generates realistic data
4. Execution: CLI receives SQL tasks via gRPC and executes them locally
5. Progress Tracking: Real-time UI shows progress for each table being seeded

Troubleshooting

Authentication Issues

# Check current auth status
seedfast me

# Re-authenticate
seedfast logout
seedfast login

Database Connection Issues

# Reconfigure connection
seedfast connect

# Or set via environment variable
export SEEDFAST_DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"

Verbose Logging

export SEEDFAST_VERBOSE=1
seedfast seed

Development

For local development and testing with custom backends, see docs/development/README_LOCAL_DEV.md.

Quick summary:

• Production builds: Connect to production backend only
• Dev builds (go build -tags dev): Support --backend-url and --grpc-url flags for local testing

Requirements

• PostgreSQL database with app schema
• Active internet connection for backend communication
• OS keychain support (macOS Keychain or Windows Credential Manager)

Platform Support

• macOS (x64, ARM64) - Uses native Keychain
• Linux (x64, ARM64) - Uses system keyring or encrypted file storage
• Windows (x64, ARM64) - Uses Windows Credential Manager

Linux Keyring Backends

Seedfast automatically detects and uses the best available backend on Linux:

1. Secret Service (GNOME Keyring, KDE Wallet) - Requires D-Bus session
2. pass (password-store) - Requires GPG setup
3. File Storage (automatic fallback) - Encrypted, works everywhere including WSL and Docker

For WSL users: File storage is automatically used. No additional setup required.

For detailed Linux keyring setup and troubleshooting, see the "Linux Keyring Setup" section in docs/INSTALL.md.

Contributing

This is a private repository. For contributions, please contact the maintainers.

License

See LICENSE file for details.

Built With

• Cobra - CLI framework
• pterm - Terminal UI
• pgx - PostgreSQL driver
• gRPC - RPC framework