You've designed your schema, run your migrations, and opened the app. Every table is empty.
Usually that means writing seed scripts, or generating a SQL file, downloading it, and importing it by hand. And every time the schema changes, you do it all again.
The FakerForge CLI cuts that down to a few terminal commands. It reads your database, generates realistic data that respects your constraints, and writes it directly into your tables.
What Is the FakerForge CLI?
The FakerForge CLI is an open-source command-line tool, distributed as a single fakerforge binary, that connects FakerForge's data generation to databases you run yourself: on your laptop, in a Docker container, or on a private server.
It keeps two connections, and they never meet:
- CLI → FakerForge API (outbound HTTPS): authentication, uploading the schema shape, and streaming generated rows back.
- CLI → your database (PostgreSQL or MySQL): introspection and inserts, using credentials stored in your OS keychain.
FakerForge never receives your database host, username, or password. It only sees the structure of the tables you choose to share: column names, types, and constraints.
Why Use the CLI Instead of a File Export?
FakerForge already exports SQL, JSONL, CSV, and XML. Those formats are still the right choice when you need a file to commit, share, or load somewhere else. The CLI is for when the destination is a database you can reach from your terminal.
- No schema copy-paste. The CLI introspects your live database, so the schema FakerForge works from always matches what's actually deployed.
- No import step. Rows go straight into your tables with parameterized, batched inserts.
- Foreign keys just work. When you push every table, the CLI inserts parents before children, so references resolve.
- Safe to repeat. Re-pulling a schema is idempotent, and
--dry-runshows what a push would do before it touches anything. - Scriptable. Every prompt has a flag or environment variable, so the same commands run in CI.
Install the CLI
Pick whichever method suits your setup. Each one installs a fakerforge binary.
Install script (Linux and macOS). It downloads the latest release and verifies its checksum:
curl -sSL https://raw.githubusercontent.com/kwasii1/fakerforge-db-agent/main/install.sh | sh
Homebrew (macOS and Linux):
brew tap kwasii1/fakerforge
brew install fakerforge
Go toolchain (any OS):
go install github.com/kwasii1/fakerforge-db-agent@latest
Prebuilt archives for Linux, macOS, and Windows on amd64 and arm64 are also on the GitHub releases page.
Check the install with:
fakerforge version
From Empty Tables to Seeded Database in Four Steps
1. Log in
Create an API key in your FakerForge API settings, then run:
fakerforge login
fakerforge whoami
The CLI checks the key against FakerForge right away and stores it in your OS keychain.
2. Connect your database
fakerforge connect --name local --driver postgres \
--host localhost --port 5432 --database myapp --user postgres
Run fakerforge connect with no flags and it will prompt you instead. The CLI pings the database before saving the connection. The password goes into your keychain, and only non-secret metadata is written to ~/.fakerforge/connections.yaml.
Use --driver mysql for MySQL.
3. Generate data
fakerforge schema pull --connection local --tables users,orders --rows 100
This introspects the users and orders tables locally, uploads only their shape, and asks FakerForge to generate 100 rows per table. Progress shows live in your terminal. Pass --async to return right away and check back later.
FakerForge's AI looks at each column's name, type, and constraints to pick a realistic generator. An email column gets email addresses, a created_at column gets sensible timestamps, and a country_code column gets real country codes.
4. Preview and push
fakerforge schemas show <schema-id>
fakerforge push --schema <schema-id> --connection local --table users --dry-run
fakerforge push --schema <schema-id> --connection local --table users
push with --table appends rows to that one table. Leave out --table (and confirm with --yes) to truncate and refill every ready table, parents first:
fakerforge push --schema <schema-id> --connection local --yes
Inserts run in batches (500 rows by default, configurable with --batch-size). If a batch fails, it's rolled back and the CLI reports how many rows succeeded.
Already Built a Schema in FakerForge?
You don't have to start in the terminal. Any schema you've built in the FakerForge web app can be pushed with the CLI.
Open the schema, click Export, and choose Database (via CLI). FakerForge shows the commands with your schema ID already filled in, ready to copy.
You can also list your schemas from the terminal:
fakerforge schemas list
Using the CLI in CI/CD
Since nothing has to be typed interactively, the CLI fits into pipelines that need fresh test data on every run:
export FAKERFORGE_API_KEY=$FAKERFORGE_KEY
export FAKERFORGE_DB_PASSWORD=$TEST_DB_PASSWORD
fakerforge connect --name ci --driver postgres \
--host localhost --port 5432 --database app_test --user postgres
fakerforge push --schema $SCHEMA_ID --connection ci --yes
fakerforge status exits with a non-zero code if authentication or any connection is broken, so you can use it as an early check that fails the build.
Security by Design
The CLI was built so you never have to trust a third party with database access:
- API key: stored in the OS keychain, with a
0600file fallback on headless machines. - Database passwords: stored in the keychain per connection, never in plain-text config.
- Inserts: parameterized queries only.
- Data: everything FakerForge generates is synthetic. No real personal data is involved at any point.
That makes the CLI safe to use against staging databases and shared development environments, where handing out connection strings would be a non-starter.
Get Started
Install the CLI, connect a database, and you can have realistic data in your tables within minutes. No seed scripts to maintain.
The FakerForge CLI docs have the full command reference, every flag, and the environment variables for scripting.