# Seedfast CLI

[![npm version](https://badge.fury.io/js/seedfast.svg)](https://www.npmjs.com/package/seedfast)
[![npm downloads](https://img.shields.io/npm/dm/seedfast.svg)](https://www.npmjs.com/package/seedfast)

> 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)

```bash
# Global installation
npm install -g seedfast

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

### Homebrew (macOS and Linux)

```bash
brew install seedfast-ai/tap/seedfast
```

### Download Binary

Download the latest release for your platform from [https://download.seedfa.st/seedfast/latest/](https://download.seedfa.st/seedfast/latest/). Pinned versions are available at `https://download.seedfa.st/seedfast/v<version>/<artifact>` (for example `https://download.seedfa.st/seedfast/latest/seedfast_Darwin_arm64.tar.gz`).

### From Source

Requires Go 1.25+:

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

## Quick Start

### 1. Authenticate

```bash
seedfast login
```

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

### 2. Connect to Database

```bash
seedfast connect
```

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

### 3. Seed Your Database

```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](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

```bash
# Check current auth status
seedfast me

# Re-authenticate
seedfast logout
seedfast login
```

### Database Connection Issues

```bash
# Reconfigure connection
seedfast connect

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

### Verbose Logging

```bash
export SEEDFAST_VERBOSE=1
seedfast seed
```

## Development

For local development and testing with custom backends, see [docs/development/README_LOCAL_DEV.md](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](docs/INSTALL.md#linux-keyring-setup).

## Contributing

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

## License

See [LICENSE](LICENSE) file for details.

## Built With

- [Cobra](https://github.com/spf13/cobra) - CLI framework
- [pterm](https://github.com/pterm/pterm) - Terminal UI
- [pgx](https://github.com/jackc/pgx) - PostgreSQL driver
- [gRPC](https://grpc.io/) - RPC framework
