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, 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.

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.

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.