Seedfast CLI

2.3.0 verified Thu Apr 23 auth: no javascript

Seedfast CLI is an AI-powered command-line interface tool designed to generate realistic test data for PostgreSQL databases. Currently at version 2.3.0, it maintains a regular release cadence with frequent patch and minor updates, indicating active development. Its core functionality involves connecting to an external backend service that leverages AI to analyze a given PostgreSQL database schema, understanding intricate table relationships and constraints. Based on this analysis, it formulates an intelligent seeding plan. Key differentiators include its ability to produce contextually appropriate and realistic test data, a rich interactive terminal interface with real-time progress tracking, a multi-worker architecture for efficient concurrent execution, and secure OAuth-style device flow authentication with OS-level credential storage. It supports multiple installation methods, including npm, Homebrew, or direct binary download, and offers dedicated integration patterns for CI/CD environments.

Common errors

error command not found: seedfast ↓

cause The `seedfast` executable is not in the system's PATH after installation.

fix

Ensure npm install -g seedfast completes successfully and npm's global bin directory is included in your system's PATH, or use npx seedfast for execution without global installation. Alternatively, install via Homebrew or directly move the downloaded binary to a PATH-accessible location.

error FATAL: password authentication failed for user "..." ↓

cause The provided PostgreSQL connection string (DSN) contains incorrect credentials or the user lacks database permissions.

fix

Re-run seedfast connect and meticulously verify the PostgreSQL connection string, ensuring the username, password, host, port, and database name are all accurate and that the user has the necessary permissions to connect to the database.

error Error: You are not authenticated. Please run 'seedfast login' first. ↓

cause The CLI requires authentication with the Seedfast backend service to perform operations like schema analysis and seeding.

fix

Execute seedfast login in your terminal. This will open your web browser to complete the authentication process with the Seedfast service.

error Error: Missing required environment variable SEEDFAST_API_KEY for non-interactive scope. ↓

cause Attempting to use Seedfast in an automated or non-interactive environment (e.g., CI/CD) without providing an API key for authentication.

fix

Set the SEEDFAST_API_KEY environment variable with a valid Seedfast API key prior to running seedfast commands in non-interactive contexts. Consult the CI/CD integration documentation for details on generating and using API keys.

Warnings

deprecated The `seedfast whoami` command has been deprecated in favor of `seedfast me` for checking authentication status. ↓

fix Use `seedfast me` instead of `seedfast whoami`.

gotcha Seedfast CLI relies on an external AI backend service for schema analysis and data generation. Operational status or changes to this service can affect the tool's functionality. ↓

fix Ensure stable internet connectivity and check Seedfast service status if encountering unexpected issues related to planning or data generation.

gotcha Initial usage requires authentication via `seedfast login`, which opens a browser for an OAuth-style device flow. Operations like `seed` and `connect` will fail without prior authentication. ↓

fix Always run `seedfast login` as the first step to authenticate with the backend service before attempting to seed or connect.

gotcha For CI/CD environments, API key authentication is required (`SEEDFAST_API_KEY` environment variable), which differs from the interactive `seedfast login` device flow used for local development. ↓

fix When integrating into CI/CD pipelines, configure `SEEDFAST_API_KEY` as an environment variable (e.g., using GitHub Actions secrets) instead of relying on interactive login.

gotcha While installable via `npm install -g seedfast`, Seedfast CLI is a Go-based binary. npm primarily acts as a wrapper/distribution mechanism. Users might prefer Homebrew or direct binary downloads for managing a non-Node.js CLI tool. ↓

fix Choose the installation method that best suits your environment and preference (npm, Homebrew, or direct binary download) while being aware of its Go-binary nature for troubleshooting.

Install

npm install seedfast

yarn add seedfast

pnpm add seedfast

Quickstart

This quickstart guides users through the initial setup, authentication with the Seedfast backend, database connection configuration, and the primary database seeding process using the `seedfast` command-line tool.

# 1. Install Seedfast CLI globally via npm or use npx
npm install -g seedfast

# Alternatively, use npx without global installation
# npx seedfast login
# npx seedfast connect
# npx seedfast seed

# 2. Authenticate with the Seedfast backend service (opens browser for device flow)
seedfast login

# 3. Connect to your PostgreSQL database (prompts for DSN)
seedfast connect
# Example DSN format: postgres://user:password@localhost:5432/dbname?sslmode=disable

# 4. Seed your database with AI-generated realistic data
seedfast seed
# The CLI will analyze your schema, present a seeding plan for approval,
# generate the data, and insert it, showing real-time progress.