FakerForge CLI

The fakerforge CLI pulls generated synthetic data directly into your local or private database. Your database credentials never leave your machine: the CLI talks to the FakerForge API over HTTPS for schemas and rows, and separately to your own Postgres/MySQL instance.

Installation

Pick one method. All of them install a fakerforge binary.

Install script (Linux/macOS)

curl -sSL https://raw.githubusercontent.com/kwasii1/fakerforge-db-agent/main/install.sh | sh

Pin a version or choose a directory:

curl -sSL https://raw.githubusercontent.com/kwasii1/fakerforge-db-agent/main/install.sh | sh -s -- v0.2.0
curl -sSL https://raw.githubusercontent.com/kwasii1/fakerforge-db-agent/main/install.sh | INSTALL_DIR=$HOME/bin sh

The script detects your OS and architecture, downloads the matching release archive, verifies its checksum, and installs the binary.

Homebrew (macOS/Linux)

brew tap kwasii1/fakerforge
brew install fakerforge

Go toolchain (any OS)

Requires Go 1.27 or newer:

go install github.com/kwasii1/fakerforge-db-agent@latest

Manual download (any OS, including Windows)

1. Open the Releases page and download the archive for your platform (fakerforge_linux_amd64.tar.gz, fakerforge_darwin_arm64.tar.gz, fakerforge_windows_amd64.zip, and so on).
2. Verify the checksum listed in checksums.txt.
3. Unpack it and place fakerforge on your PATH.

Check the installed version with fakerforge version, and update by repeating your install method.

Quick Start

The CLI talks to https://fakerforge.com by default — no configuration needed. Authenticate, register your database, generate, and push:

fakerforge login
fakerforge whoami

fakerforge connect --name local --driver postgres \
  --host localhost --port 5432 --database myapp --user postgres
# Or run `fakerforge connect` with no flags for interactive prompts.

fakerforge schema pull --connection local --tables users,orders --rows 100

fakerforge schemas show <schema-id>
fakerforge push --schema <schema-id> --connection local --table users

Commands

Account

• fakerforge login [--api-key KEY] — validates the key against the API immediately and stores it in your OS keychain. The flag wins, then the FAKERFORGE_API_KEY env var, then an interactive prompt.
• fakerforge logout — removes the stored API key.
• fakerforge whoami — shows the currently authenticated user.

Database connections

• fakerforge connect — interactive prompts for name, driver, host, port, database, user, and password.
• fakerforge connect --name NAME --driver postgres|mysql --host H --port P --database D --user U [--password P] — scriptable form. Passwords also come from FAKERFORGE_DB_PASSWORD or a prompt; never pass one as a bare positional argument.
• fakerforge connect --list — list saved connections (metadata only, never secrets).
• fakerforge connect --remove NAME — delete a connection and its stored password.
• fakerforge connect --default NAME — change the default connection.

The connection is pinged before it is saved. DB passwords live in the OS keychain under conn:{name}; only non-secret metadata is stored in ~/.fakerforge/connections.yaml.

Schemas

• fakerforge schema pull --connection NAME [--tables A,B] [--rows N] — introspects your database locally, uploads the schema shape only (never row data), generates data, and polls until it is ready with a live progress bar. Re-pulls are idempotent via fingerprint. Useful flags: --rows (default 100, capped by your plan), --name, --force, --regenerate, --async, --timeout, --interval, --no-progress for CI.
• fakerforge schemas list [--table TABLE] [--format table|json] — list your schemas.
• fakerforge schemas show SCHEMA_ID [--table TABLE] — per-table rows and status; with --table, columns (type, nullable, primary, unique, and the table.column a foreign key references), the table's parents, rules, and a sample.

Push

• fakerforge push --schema ID --connection NAME --table TABLE [--batch-size N] [--dry-run] — append rows into one table.
• fakerforge push --schema ID --connection NAME [--yes] [--append] — TRUNCATE + INSERT every ready table, parents-first. Always confirmed unless --yes; --append inserts without truncating.

The API returns each schema's insert_order (tables listed parents first) so pushes satisfy foreign keys. This matters most on PostgreSQL, which has no session switch to disable them.

Every streamed row is validated against the target table's constraints (integer ranges, string lengths, enum values, NOT NULL, uniqueness) before anything is written. A bad row aborts the push with the exact row, column, and value instead of a raw database error.

System

• fakerforge status — checks API auth, pings saved connections, and compares your CLI version against the latest release. Exits non-zero when something is broken, so it works as a CI pre-flight check.
• fakerforge version — prints the CLI version.

What Generated Data Guarantees

Data generated for a pulled schema follows the same rules as the web app (see Relationships and Integrity):

• Foreign keys: every foreign key value comes from a generated parent row.
• Unique and composite keys: one-to-one keys, unique columns and multi-column unique keys never repeat.
• Row caps: a table is capped when your requested --rows exceeds what its constraints allow, for example a one-to-one child of a smaller parent table.
• Realistic values: column values follow realistic profiles (see Realistic Values).

A pull that selects a child table without its required parent fails generation with a message naming the missing parent. Include the parent with --tables.

Environment Variables

• FAKERFORGE_API_URL — API base URL override (default https://fakerforge.com; only needed for local development).
• FAKERFORGE_API_KEY — API key override.
• FAKERFORGE_DB_PASSWORD — database password for scripting.
• FAKERFORGE_HOME — config directory override (default ~/.fakerforge).

Security Model

• Two connections, never bridged: CLI to API for data, CLI to your database for writes.
• Secrets live in the OS keychain, with a 0600 file fallback on headless machines.
• Pushes use parameterized queries only, roll back the failed batch, and abort with per-table tallies — no silent partial writes.
• If a connection host looks like production (prod/production), pushes require an extra confirmation.

Troubleshooting

• Connection or ping failures: verify host, port, and TCP access; supply the password via --password, FAKERFORGE_DB_PASSWORD, or the prompt.
• No prompt on a server: export FAKERFORGE_API_KEY and FAKERFORGE_DB_PASSWORD since keychains need an interactive session.
• A push aborted with a value-rejected error: the message names the row, column, and value — re-run schema pull --regenerate or fix the data.
• status exits non-zero: its report tells you whether auth, a connection, or the CLI version is at fault.
• Generation failed with "references …, which is not selected for generation": add the parent table to --tables, or make the foreign key column nullable.