fluid forge

Author a data product contract with an AI copilot, an offline guided interview, or an empty skeleton. By default forge writes contract.fluid.yaml and .fluid/forge-receipt.json; a scaffold (--scaffold), a CI pipeline (--ci) and engine artifacts add files.

Syntax

fluid forge [OPTIONS]
fluid forge data-model <from-intent|from-ddl|from-source|validate|diff|dump-ddl|learn> [OPTIONS]

Examples

# Interactive AI copilot
fluid forge

# Target a provider or a domain
fluid forge --provider gcp
fluid forge --domain finance

# Choose the model
fluid forge --llm-provider openai --llm-model gpt-4.1-mini
fluid forge --llm-provider gemini --tiered --require-llm

# No model: an empty contract, or a guided interview with no network
fluid forge --blank --target-dir ./out
fluid forge --offline --non-interactive --yes --target-dir ./out

# Keep the contract in fragments, and add a CI pipeline
fluid forge --fragments --ci github_actions

# Pick up a paused run
fluid forge --resume

For a guided walkthrough of the forge journeys, see AI Forge And Data-Model Journeys.

Key options

Project

Layout

Both apply on the default AI-copilot path only. See Single file or fragments? and Projects fluid forge writes.

AI config

Show the model plan per provider with fluid ai models, and check connectivity with fluid ai test.

Prompt profiles and overlays

An overlay is a YAML file that patches labelled prompt sections with replace, append or prepend, and can add validator_rules that the generated contract must satisfy. A name resolves to <name>.yaml under ~/.fluid/agent_specs/prompt_overlays/ (or under $FLUID_USER_HOME), then to the overlays bundled with the CLI. Overlays are parsed with a safe YAML loader, and a stack that drops a load-bearing instruction (for example "Return strict JSON only.") is rejected. Set FLUID_OVERLAY_STRICT=1 to reject any overlay without a valid ed25519 signature; a present but invalid signature is rejected in every mode.

The active profile and overlays are written into the contract's provenance:

metadata:
  provenance:
    ...
    prompt_profile: eu-gdpr-strict
    prompt_overlays:
    - pii-lockdown

An unknown profile fails with unknown prompt profile and lists the available names.

Discovery and memory

Composition and refinement

Resume

CI scaffolding

Single file or fragments?

A fragment-layout contract is a root file whose builds, exposes, sovereignty and accessPolicy entries are $ref pointers into fragments/. validate, plan and apply resolve the references themselves, so you run them on the root. Forge's own closing hint says so: FLUID auto-bundles fragments when you run validate, plan, or apply. See Contract references ($ref) for the resolution rules, and fluid split and fluid bundle for converting between the layouts.

On the default AI-copilot path, forge chooses the layout in this order:

1. --fragments forces fragments. --no-fragments forces one flat file.
2. A fragments/ directory that already exists in the target keeps the fragment layout.
3. Otherwise, forge splits the contract when it has two or more builds, two or more exposes, or a sovereignty or accessPolicy block. A single-build, single-expose contract with neither block stays flat.

The split is mechanical, not a model call:

contract.fluid.yaml                  # root, with $ref entries
fragments/
├── sovereignty.yaml                 # when the contract has sovereignty
├── access-policy.yaml               # when the contract has accessPolicy
├── builds/<build-id>.yaml
└── exposes/<expose-id>.yaml

When forge splits, it prints the fragment files, then Layout: Fragment-first (modular) with two hints: fluid bundle to reassemble one contract, and --no-fragments to get a single file next time.

If the product federates, note that fluid contract digest and the federation check read only the root file, so an edit inside a fragment does not change the digest. See fluid contract digest.

Resume, fork and time-travel

An AI-copilot run writes its stages to .fluid/agents/<run-id>/, so a paused or interrupted run can be resumed from there. (fluid forge --blank created no .fluid/agents/ directory in the 0.18.1 test, so it has nothing to resume.)

fluid agents list --incomplete        # find the paused run
fluid forge --resume                  # resume the most recent paused run
fluid forge --resume 1a2b3c           # resume one run, by id or prefix
fluid forge --resume 1a2b3c --from-stage builder       # re-run from the builder stage
fluid forge --fork 1a2b3c --from-stage builder         # same, under a new run id
fluid forge --resume --or-fail        # exit 1 instead of starting fresh when nothing is paused

The stages, in order, are logical, contract_forge, builder, readme, transformation, validator, enrichment and judge. A misspelled stage fails with a "did you mean" hint and the list. --from-stage without --resume RUN_ID or --fork RUN_ID fails with --from-stage requires --resume <run-id> or --fork <run-id>. --fork without --from-stage fails with --fork requires --from-stage (which stage of the source run to fork from).

With neither flag, forge offers a paused run when it finds one and you are at a terminal. --no-resume skips the offer, and FLUID_FORGE_AUTO_RESUME=1 accepts it. fluid agents lists, shows and prunes runs.

CI scaffolding after forge

--ci asks forge to write a pipeline once the contract exists:

fluid forge --blank --ci github_actions --ci-complexity basic --non-interactive --yes --target-dir o

o/
├── .env.ci.example
├── .fluid/
│   ├── ci-state.json
│   └── forge-receipt.json
├── .github/workflows/fluid-pipeline.yml
└── contract.fluid.yaml

ci-state.json records the provider, complexity and inputs that produced the committed files, so a later run can tell when they drift. Forge decides whether to scaffold CI in this order, and stops at the first rule that answers:

1. FLUID_FORGE_AUTO_CI set to 0, false, no or off disables it.
2. --no-ci.
3. --ci PROVIDER.
4. The provider recorded in .fluid/ci-state.json.
5. The provider saved in copilot memory.
6. An interactive menu.
7. Nothing, when none of the above applies and there is no terminal.

For finer control over what the pipeline contains, use fluid generate ci (generate) or fluid generate-pipeline.

Forging a data model

The model-first path is fluid forge data-model. It writes a Fluid contract, a .model.json logical sidecar, and a human-readable Mermaid + Markdown model document.

fluid forge data-model from-intent intent.yaml -o customer_orders.fluid.yaml
fluid generate transformation customer_orders.fluid.yaml -o ./dbt_customer_orders --dbt-validate

Use from-intent for YAML/JSON business intent files, from-ddl for SQL DDL, and from-source for configured metadata catalogs.

The intent format is discoverable from the CLI:

fluid forge data-model from-intent --example
fluid forge data-model from-intent --example retail
fluid forge data-model from-intent --example telco
fluid forge data-model from-intent --example finance
fluid forge data-model from-intent --schema
fluid forge data-model from-intent --validate intent.yaml

Data-model flags

from-intent, from-ddl and from-source share most of their flags. fluid forge data-model <subcommand> --help prints the full list.

from-ddl takes --ddl FILE... and --source-type (snowflake, bigquery, postgres, postgresql, oracle, mysql). from-source takes --source, --credential-id, --database, --schema, --catalog, --tables, --name, and --uri for the JDBC sources; --allow-metadata-service lets the credential resolver use cloud workload identity.

See the Forge Data Model guide for the field mapping, generated artifacts, deterministic mode, strict LLM mode, and dbt generation flow.

For hosted provider smoke tests, export a provider key in your shell and use --require-llm. Do not paste API keys into command examples, contracts, intent files, or docs.

Seeding from an existing ODCS or Bitol ODPS contract

If you already have an upstream ODCS or Bitol ODPS contract (your own, or one published by an upstream team), use --seed-from to skip the discovery phase entirely:

fluid forge --seed-from ./upstream.odcs.yaml
fluid forge --seed-from ./upstream.odps.yaml
fluid forge --seed-from ./bitol-bundle/             # directory with ODPS + sibling ODCS files

Accepted entry shapes:

• *.odcs.yaml — a lone Open Data Contract Standard v3.1.0 file
• *.odps.yaml — a Bitol ODPS data product file
• a directory bundle containing the ODPS doc plus sibling <contractId>.odcs.yaml files (or only ODCS files)

Remote seeds — opt in to http(s) fetch

fluid forge --seed-from https://catalog.example.com/products/orders.odps.yaml --seed-allow-remote

Remote http(s) contractId references are off by default (the May 2026 SSRF hardening). --seed-allow-remote opts in to remote fetch; the fetcher rejects internal/private IPs, pins the validated IP, and caps the body at 10 MiB. Only enable when you trust the upstream catalog. See network safety for the full SSRF posture.

Where the seed lands

The seed pre-processor lives at fluid_build/cli/forge_copilot_seed.load_seed(...) and is callable as a library. The copilot runtime hand-off plus the ground-truth diff guard (rejecting an LLM rewrite that mutates schema fields the seed pinned) are wired into the standard fluid forge flow.

Forging from a source catalog

If your team already maintains rich metadata (descriptions, tags, lineage, classifications) in a data catalog, you can skip the intent / DDL inputs entirely and forge directly from the catalog:

fluid ai setup --source snowflake --name snowflake-prod      # one-time setup
fluid forge data-model from-source \
  --source snowflake \
  --credential-id snowflake-prod \
  --database BIZ_LAB --schema SEEDED \
  --technique data-vault-2 \
  -o biz_lab.fluid.yaml

Seven catalogs are supported — Snowflake Horizon, Databricks Unity, BigQuery, Dataplex, AWS Glue, DataHub, Data Mesh Manager. Each ships with privilege grant scripts, auth methods, and an end-to-end demo. See the catalogs index for the full list.

The same flow is exposed via the MCP forge_from_source tool, so Claude Code / Cursor agents can drive a catalog forge from inside the editor.

Mode picker, refine, compose

Bare fluid forge (TTY, no flags) lands on a 5-mode menu instead of dropping straight into AI:

What kind of run is this?
  1. AI Copilot                  — full interview, LLM-driven (default for fresh products)
  2. Compose from existing       — build on top of products already in the workspace
  3. Refine a contract           — load a contract, ask 'what to change?'
  4. Template                    — start from one of the 5 built-in templates
  5. Blank scaffold              — empty contract, no AI

The picker pre-highlights based on a parallel welcome scan that runs in <50 ms. Skip with FLUID_FORGE_NO_PICKER=1.

--from-product — composition

Pick one or more upstream products; Forge resolves them, validates composition rules (SDP rejects upstreams; ADP/CDP accept SDP+ADP — see Product Types), and pre-fills consumes[]:

fluid forge --from-product bronze.crm_orders
fluid forge --from-product bronze.crm_orders --from-product bronze.crm_customers
fluid forge --from-product-list ./upstreams.json

--refine — load a contract and tweak

fluid forge --refine                          # auto-discover from cwd
fluid forge --refine ./products/orders.fluid.yaml

Loads the contract, asks "what to change?", feeds the contract verbatim to the LLM as the seed. One question, no full interview.

Slash commands inside the interview

Pre-write preview panel

Before any file is written, Forge renders a panel showing files, cost, and run-id so users see exactly what they're about to commit to. --yes skips the confirmation prompt but the panel still renders. Suppress with FLUID_FORGE_NO_PREVIEW=1.

For the full picture see Guided fluid forge UX.

Headless agent mode

fluid forge --agent is a preset for agentic IDEs (Kiro, Cursor, Claude Code, Cline) and other automation that drives Forge without a human at the prompt:

fluid forge --agent
fluid forge --agent --emit-plan

• It bundles --yes and FLUID_FORGE_NO_*=1, and emits JSON-Lines progress events on stdout so the calling agent can stream status.
• It defaults to --blank, so it can never drop into the interactive mode picker.
• --emit-plan makes the run emit a single deterministic forge.plan event — the per-product-type (SDP / ADP / CDP) field checklist for the agent to fill in — instead of authoring the contract itself.

This is the CLI half of the agentic-IDE flow. Set the editor side up with fluid scaffold-ide, and the in-editor tools come from the MCP server.

Notes

• The current promoted syntax is fluid forge, not fluid forge --mode copilot.
• Use --domain for built-in domain guidance instead of the older --mode agent flow shown in some legacy docs.
• Discovery and memory guides live in the advanced docs: discovery and memory.

Industry skills

--domain gives the copilot a role such as finance or retail. For deeper vocabulary, typical products and regulatory constraints, install an industry skills pack with fluid skills. The copilot reads the pack from .fluid/skills.yaml in the project.

fluid skills install telco