Scaffold a project
The twilldb CLI generates a ready-to-run starter app around the engine — a package.json, a connection string for the backend you choose, a first table, and a runnable script — so you go from nothing to a working embedded database in one command.
Install the CLI
The CLI ships through a Homebrew tap (a self-hosted formula repo). Tap it once, then install:
brew tap bihaviour/twilldb
brew install twilldbOr as a single fully-qualified command (Homebrew resolves a tapped formula as user/repo/formula, so the name repeats):
brew install bihaviour/twilldb/twilldbBuilding from a checkout instead
If you have the repo cloned, you can build and run the CLI directly: cargo run -p twilldb-cli -- new myapp, or cargo install --path crates/cli to put twilldb on your PATH.
Create a project
twilldb new notes
cd notes
bun install
bun run startThat generates a Bun project and runs a first script against a local file:// database — no server, no infrastructure. The native engine ships with @twilldb/bun as a per-platform optional dependency, so there is no cargo build step.
What you get:
| File | Purpose |
|---|---|
package.json | depends on @twilldb/bun; a start script |
app.ts | opens the database, creates a table, inserts in a transaction, queries |
tsconfig.json, .gitignore | Bun/TypeScript config; ignores the generated *.db files |
README.md | how to run it and how the backend is selected |
Interactive mode
On a terminal, anything you don't pass as a flag is asked interactively. Run a bare command and the wizard walks you through it:
$ twilldb new
twilldb — new project
Project name: search
Client [bun] (bun/node/php; rust coming soon):
Backend [file] (file/s3): s3
Include a vector-search (HNSW) starter? [y/N]: y
about to create:
name search
client bun
backend s3
vector yes
proceed? [Y/n]:
created search/ (6 files — bun client, s3 backend, vector starter)Only the unspecified fields are asked — twilldb new app --backend s3 still prompts for the rest but skips the backend. Press Enter to accept the bracketed default.
Scripts and CI never block
The wizard runs only when stdin is a real terminal. In a pipe or a CI job, twilldb takes the defaults for any omitted option (and still errors if new has no name). Pass -y, --yes to force that non-interactive behavior on a terminal too.
Options
| Flag | Default | Effect |
|---|---|---|
-c, --client <bun|node|php> | bun | client ecosystem. bun, node, and php generate runnable embedded starters; a native rust starter is on the roadmap. See Node / PHP. |
-b, --backend <file|s3> | file | writes the connection string: file://./<name>.db or an s3://your-bucket/<name> placeholder. |
--vector | off | adds a vectors.ts starter — a vector(3) column, an HNSW index, and a top-k nearest-neighbour query. |
-y, --yes | off | accept defaults and never prompt (forces non-interactive on a terminal). |
twilldb new web --client node # Node embedded starter (@twilldb/node)
twilldb new api --client php # PHP embedded starter (twilldb/twilldb)
twilldb new search --vector # add a vector-search starter
twilldb new app --backend s3 # write an s3:// connection string
twilldb init # scaffold into the current directoryA node starter installs and runs with npm install / npm start; a php starter with composer install / composer start. Each embeds the engine in-process over the same C ABI — see the per-runtime guides for Node (Next.js, Astro, Vite) and PHP (Laravel, CodeIgniter).
The backend is just the connection string
--backend only changes the URL written into app.ts. The engine selects the storage backend purely by the URL scheme at open() time, so your code is identical for file:// and s3://. See Storage backends for credentials.