fluid forge

Use AI-assisted scaffolding when you want domain hints, local discovery, or project memory during project creation.

Syntax

fluid forge [OPTIONS]

Key options

Project

AI config

Discovery and memory

Examples

fluid forge
fluid forge --provider gcp
fluid forge --domain finance
fluid forge --llm-provider openai --llm-model gpt-4.1-mini
fluid forge --llm-provider gemini --tiered --require-llm
fluid forge --blank --target-dir ./out

For a guided walkthrough of every public forge journey, see AI Forge And Data-Model Journeys.

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

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 — fluid skills

--domain gives the copilot a high-level role (finance, healthcare, retail, telco). For deeper domain knowledge — the vocabulary, typical data products, standard fact tables, regulatory constraints of an industry — install an industry skills pack. Skills live in .fluid/skills.yaml inside the project; the compiled form .fluid/skills.compiled.json is what the copilot loads at runtime.

fluid skills <action>

Subcommands

Examples

fluid skills install telco
fluid skills show
fluid skills compile
fluid skills update

Run fluid skills compile after any manual edit to skills.yaml to keep the compiled form in sync. fluid skills update is the right command after upgrading the CLI — it rewrites the tools list so the copilot sees the newest fluid_* entries.