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.

Editor extension#

Every install channel above bundles the forgedb-lsp language server beside the CLI. To light it up in your editor, install the ForgeDB Schema Language extension — .forge syntax highlighting plus compiler-backed diagnostics, completion, hover, goto-definition, and rename. It's on the VS Code Marketplace and Open VSX, so it works in VS Code, Cursor, VSCodium, Windsurf, and code-server:

code --install-extension forgedb.forgedb   # or search "ForgeDB" in the Extensions view

The language features are served by forgedb lsp, so the extension needs the CLI on your PATH (or set forgedb.path). Full feature list, settings, and per-editor install notes are on the editor support page.

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.