fdb CLI

fdb is the command-line tool for FoundationDB, the Record Layer, and SQL. It starts local development clusters, reads and writes protobuf records, manages indexes, and runs SQL without an application server or cgo.

Protobuf records and indexes

Compile an annotated schema, work with records, and inspect indexes.

SQL and catalog discovery

Create a SQL schema, query rows, and inspect its Record Layer store.

Connections and metadata

Configure clusters, contexts, descriptor sets, and persisted metadata.

Command reference

Commands, flags, output formats, write guards, and completions.

Install

The renamed CLI has not had a tagged release yet. Build from a current checkout with the Go version in go.mod:

git clone https://github.com/birdayz/fdb-go.git
cd fdb-go
go build -o .tmpbuild/fdb ./cmd/fdb
export PATH="$PWD/.tmpbuild:$PATH"

The release installer (curl -fsSL https://fdb.dev/install.sh | sh) and go install fdb.dev/cmd/fdb@<tag> require a root-module release containing cmd/fdb; the installer also needs that release’s published fdb archives. Those release artifacts are not available yet. Existing older releases and @latest cannot supply this renamed CLI; use the checkout build above.

Check the installation:

fdb version
fdb --help

Start a local cluster

With Docker running:

fdb dev up
fdb tx read-version
fdb dev status

fdb dev up starts and initializes a single-node FoundationDB container, writes its cluster file, and activates a CLI context. Progress goes to stderr; stdout is the cluster-file path. You do not need to create a config file first.

The container publishes its port on 127.0.0.1. It is an unauthenticated, throwaway development database, not a production deployment or an isolation boundary against local users. A local Docker socket is required; remote Docker daemons and clients in other containers are not supported by this helper.

For a cluster you already run, see connections and contexts.

Choose a workflow

Native protobuf records: follow the Record Layer tutorial. Give the CLI an annotated protobuf descriptor set; no application plugin or metadata dumper is required.
SQL: follow the SQL tutorial. SQL schemas use the relational catalog, not a descriptor-set flag.
An existing application store: select its cluster, keyspace, and metadata source.

Command groups

Command	Purpose
`fdb rl`	Record Layer records, indexes, stores, metadata, statistics, keyspaces, and status
`fdb sql`	Interactive SQL, one-shot statements, and SQL scripts
`fdb tx`	Transaction utilities such as `read-version`
`fdb dev`	Local FoundationDB development containers
`fdb config`	Config files and named contexts
`fdb version`	Binary and Go build information
`fdb completion`	Shell-completion scripts

Record Layer operations live under fdb rl, including relational catalog discovery at fdb rl meta catalog. Use fdb <command> --help for help on a command, or read the full reference.

Local files and cleanup

Configuration defaults to ~/.fdb/config.yaml; FDB_CONFIG selects another path. fdb config path prints the path in use. Interactive SQL history lives at ~/.fdb/sql_history.

When you are finished with the default development cluster:

fdb dev down

This removes the container and its data. It leaves the CLI context and cluster file in place. For a named instance, pass the same --name used at startup.