CLI

fabriq is one binary wrapping a forge app in forge/cli RunApp. The serve path runs the worker; the operator commands open their own stores from flags and environment, run once, and exit.

Global flag and environment01

A single global flag overrides the Postgres DSN for ad-hoc operator use:

fabriq --dsn postgres://owner:...@pg:5432/fabriq inspect state -t acme

--dsn falls back to FABRIQ_POSTGRES_DSN. If neither is set, any command that needs Postgres errors with postgres DSN required: pass --dsn or set FABRIQ_POSTGRES_DSN. Operator commands accept --dsn at both the command and subcommand level.

Note

Operator commands take a single --dsn and are not shard-aware. In a sharded deployment, point --dsn at one shard's database and run the command once per shard — including rebuild --all-tenants, which then iterates only that shard's tenants.

The serve path reads everything from the environment:

Variable	Required	Meaning
`FABRIQ_POSTGRES_DSN`	yes (to serve)	Source-of-truth Postgres DSN.
`FABRIQ_REDIS_ADDR`	yes (to serve)	Redis address for the event stream and subscriptions.
`FABRIQ_FALKORDB_ADDR`	no	Enables the graph projection consumer.
`FABRIQ_ELASTICSEARCH_ADDRS`	no	Comma-separated; enables the search projection consumer.
`FABRIQ_HTTP_ADDR`	no	Health + `/metrics` bind address (default `:8081`).
`FABRIQ_RECONCILE_INTERVAL`	no	Scheduled reconciler cadence (Go duration; `0` disables; default 5m).

serve — run the worker02

fabriq serve        # explicit
fabriq start        # alias
fabriq run          # alias
fabriq              # no args: defaults to serve

serve runs the background plane until SIGTERM: the leader-elected outbox relay, the CRDT document materializer, the scheduled reconciler, and the graph and search projection consumers. It requires FABRIQ_POSTGRES_DSN and FABRIQ_REDIS_ADDR; FalkorDB and Elasticsearch consumers start only when their addresses are set. Singletons are leader-elected, so any number of replicas is safe — see Deployment.

migrate — schema migrations03

Migrations are a discrete deploy step, never run at app startup, and connect as the schema owner. Full detail in Migrations.

bash

fabriq migrate up

inspect — registry and projection state04

fabriq inspect registry          # dump registered entity specs (no DB needed)
fabriq inspect state -t acme     # projection state for a tenant

inspect registry prints every registered entity: name, kind, table, graph node, search index, declared edges, and subscription scopes. It reads no database.

inspect state needs --dsn/FABRIQ_POSTGRES_DSN and --tenant/-t. For the graph and search projections it prints the model version, status, target name, and event-stream position:

graph   model_v3   status=live      target=tenant_acme_v3            stream=...
search  model_v1   status=live      target=v1                        stream=...

rebuild — blue-green projection rebuild05

fabriq rebuild --tenant acme --projection graph   --falkordb falkordb:6379
fabriq rebuild --tenant acme --projection search  --elasticsearch https://es:9200

Rebuilds one projection for a tenant by replaying the Postgres snapshot into a new target, then flipping the pointer. Flags:

Flag	Default	Meaning
`--tenant`, `-t`	—	Tenant to rebuild (required unless `--all-tenants`).
`--projection`, `-p`	`graph`	`graph` or `search`.
`--falkordb`	`FABRIQ_FALKORDB_ADDR`	Required for graph rebuilds.
`--elasticsearch`	`FABRIQ_ELASTICSEARCH_ADDRS`	Required for search rebuilds.
`--all-tenants`	`false`	Rebuild every tenant in projection state.
`--drop-old`	`false`	Drop the old target immediately instead of soaking.

Without --drop-old, the new target is left soaking and the command prints the finalize line to run after the soak window. End the soak with:

fabriq rebuild finalize --tenant acme --old tenant_acme_v2 --falkordb falkordb:6379

finalize flags: --tenant/-t, --old (the old target to drop), and --falkordb (or FABRIQ_FALKORDB_ADDR). Full procedure and semantics in Rebuild & Reconcile.

reconcile — drift reconciliation06

fabriq reconcile --tenant acme --falkordb falkordb:6379                  # dry run
fabriq reconcile --tenant acme --falkordb falkordb:6379 --repair        # heal
fabriq reconcile --tenant acme --elasticsearch https://es:9200 --repair

Compares per-aggregate versions between Postgres and each configured projection. Flags:

Flag	Default	Meaning
`--tenant`, `-t`	—	Tenant to reconcile (required).
`--falkordb`	`FABRIQ_FALKORDB_ADDR`	Reconcile the graph projection.
`--elasticsearch`	`FABRIQ_ELASTICSEARCH_ADDRS`	Reconcile the search projection.
`--repair`	`false`	Re-emit drifted aggregates through the outbox.

You must pass at least one of --falkordb / --elasticsearch. Without --repair it is a dry run that lists drift. With --repair it re-emits each drifted aggregate through the outbox; it never writes an engine directly. The worker also runs this on a schedule — see Rebuild & Reconcile.

Forge built-ins07

fabriq info          # app information
fabriq health        # check app health
fabriq extensions    # list registered extensions

These come from forge/cli and reflect the worker app's wiring.

Migrations→

The DDL authority and the expand/contract rules behind migrate.

Rebuild & Reconcile→

Blue-green rebuild and drift reconciliation in depth.

← Previous

Remote protocol

Migrations