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

$3

``bash


Global installation

npm install -g seedfast

Or use with npx (no installation required)

npx seedfast seed
`

$3

`bash
brew install argon-it/tap/seedfast
`

$3

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

$3

Requires Go 1.25+:

`bash
git clone
cd cli
go build -o seedfast
`

Quick Start

$3

`bash
seedfast login
`

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

$3

`bash
seedfast connect
`

Enter your PostgreSQL connection string:
`
postgres://user:password@localhost:5432/dbname?sslmode=disable
`

$3

`bash
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

`bash
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:

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

GitHub Actions Example:

`yaml
- 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

$3

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

$3

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

$3

`bash


Check current auth status

seedfast me

Re-authenticate

seedfast logout
seedfast login
`

$3

`bash


Reconfigure connection

seedfast connect

Or set via environment variable

export SEEDFAST_DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"
`

$3

`bash
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

$3

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