Installation

ForgeDB ships as a single CLI binary, forgedb (plus a bundled forgedb-lsp language server). Pick whichever channel fits your stack — they all give you the same tool, version-locked to the crate release.

Shell installer#

The fastest path on macOS and Linux — downloads the right prebuilt binary for your platform and puts forgedb + forgedb-lsp on your PATH:

curl -fsSL https://get.forgedb.dev/install.sh | sh

That's an alias for the installer attached to the latest GitHub Release. The direct form (identical bytes) is:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/hoodiecollin/forgedb/releases/latest/download/forgedb-installer.sh | sh

Homebrew#

macOS and Linux, via the project tap:

brew install hoodiecollin/tap/forgedb

brew upgrade hoodiecollin/tap/forgedb later. The formula repackages the same release binary — no Rust toolchain.

npm / bun#

Published under a personal scope (the unscoped forgedb name was unavailable). The package downloads the matching prebuilt binary on install:

npm install -g @hoodiecollin/forgedb     # or: bun add -g @hoodiecollin/forgedb
npx @hoodiecollin/forgedb --help         # or: bunx @hoodiecollin/forgedb --help

PyPI / uv#

The PyPI project is hoodiecollin-forgedb (bare forgedb is taken); the installed command is still forgedb. The wheels are self-contained — they bundle the binary, no build step:

uv tool install hoodiecollin-forgedb        # command on PATH: forgedb
pip install hoodiecollin-forgedb
uvx --from hoodiecollin-forgedb forgedb --help

Docker#

A multi-arch image (linux/amd64 + linux/arm64) bundling forgedb and forgedb-lsp, published on every release. Bind-mount your schema/output dir at /work:

docker run --rm -v "$PWD:/work" ghcr.io/hoodiecollin/forgedb generate all --output ./generated
# also on Docker Hub:
docker run --rm -v "$PWD:/work" hoodiecollin/forgedb --help

The image repackages the same release binaries as the native install (no runtime Rust toolchain).

Nix (flake)#

Run without installing, or add ForgeDB to your own flake. Builds from source over the committed Cargo.lock:

nix run    github:hoodiecollin/forgedb -- --help     # run once
nix profile install github:hoodiecollin/forgedb      # install to your profile
nix develop github:hoodiecollin/forgedb              # dev shell (rust + tooling)

In a flake, add forgedb.url = "github:hoodiecollin/forgedb"; and reference forgedb.packages.${system}.default.

cargo install (from crates.io)#

The canonical path if you already have a Rust toolchain (≥ 1.85, edition 2024):

cargo install forgedb            # add --features lsp to also build forgedb-lsp
cargo install forgedb --force    # update later

This builds the CLI from the published crates and drops forgedb in ~/.cargo/bin.

Direct download#

Each release also attaches raw archives — grab the one for your platform, extract, and put the binaries on your PATH:

tar -xf forgedb-<target>.tar.xz
sudo mv forgedb forgedb-lsp /usr/local/bin/     # or anywhere on your PATH
forgedb --help

From source#

Track the tip of main (or install before a release is cut):

# latest from git
cargo install --git https://github.com/hoodiecollin/forgedb forgedb
 
# or from a clone
git clone https://github.com/hoodiecollin/forgedb
cd forgedb
cargo build --release          # binary at target/release/forgedb
cargo install --path .         # or install it onto your PATH

Both build the whole workspace from source, so no crates need to be published first.

Generated client SDKs (per ecosystem)#

Installing the CLI is only half the story — the CLI generates a typed REST client for each language on your stack. These aren't installed from a registry; you generate them from your schema and vendor them into your app. One command each:

Node.js / Bun#

forgedb generate node --sdk     # → generated/types.ts  (bun --sdk is equivalent)

Emits a TypeScript client plus a publishable package.json/tsconfig.json. Import ForgeDBClient from the generated types.ts.

Python#

forgedb generate python --sdk   # → generated/python-sdk/forgedb_client.py

A stdlib-urllib client (no runtime deps) plus a pyproject.toml. Import ForgeDbClient from forgedb_client.

Rust#

forgedb generate rust --sdk     # → generated/rust-sdk/  (a reqwest client crate)

A reqwest-based client crate — add it as a path/git dependency and use ForgeDbClient.

Go#

forgedb generate go --sdk       # → generated/go-sdk/client.go

A net/http client package plus a go.mod. Construct with client.NewClient(...).

See the quickstart for end-to-end usage of each, and forgedb generate for the full generator matrix (including the in-process native bindings — PyO3, NAPI-RS, and the browser WASM replica).

Substrate crate versions#

A ForgeDB-generated app is not dependency-free: its generated Rust code links a set of small, schema-agnostic runtime crates published on crates.io (the "substrate"). forgedb init pins these in the generated Cargo.toml, so you don't manage them by hand. This table records what a given CLI generates against.

These crates know nothing about any specific schema. Every schema-tailored surface — types, tables, queries, filters, relations, API routes — is generated per app at compile time. See core concepts for the identity invariant.

Next#

Once forgedb is on your PATH, walk the full loop in the quickstart.