Getting Started

Run your first data product locally in a few minutes, then move to cloud targets when you are ready.

Why it matters You ship a real, versioned data product on your laptop in minutes — no cloud account, no platform-team ticket. The same contract.fluid.yaml you run locally is the one you later ship to any cloud; only binding.platform changes.

What you skip with Fluid Forge

You're about to ship a working data product in 30 seconds. The five-tool stack you'd otherwise need: gone.

• No Airflow DAG to write or maintain. fluid generate schedule --scheduler airflow|dagster|prefect emits the right artifact.
• No JVM, no cluster, no heap tuning. engine: duckdb runs embedded.
• No Snowflake permission sprawl. accessPolicy.grants compiles to native GRANT statements.
• No Terraform for data IAM. policy-apply emits BigQuery / Snowflake / S3 IAM bindings from the same contract.
• No 27 questions before you ship. fluid forge infers from your local files; you answer 4.

→ See the full comparison: Forge vs dbt / Dagster / Terraform / Snowpark.

What this guide assumes

• Python 3.10+
• pip
• No cloud credentials required for the local-first path

Install the CLI

The current docs baseline is 0.10.0 — the stable tag was cut on 2026-06-27:

pip install --upgrade data-product-forge
pip install "data-product-forge==0.10.0"    # exact pin

Pre-releases (when published) ship to PyPI as PEP 440 pre-releases — pip install skips them by default. The --pre flag opts in.

Dependency floor (what you'll see in pip install)

0.10.0 pins minimum versions on several deps to close known CVEs:

• jinja2 >= 3.1.6 (CVE-2025-27516), h11 >= 0.16 (CVE-2025-43859), cryptography >= 46.0.7 (CVE-2026-26007 / 39892 / 34073)
• litellm >= 1.83.7, < 2 (CVE-2026-42208) — skips the compromised 1.82.7 / 1.82.8 PyPI artifacts
• mcp >= 1.20 (required for fluid mcp serve sampling), keyring >= 24.0 (now a hard dependency — catalog source secrets default to the OS keyring)

Check the installed CLI and basic system health:

fluid version
fluid doctor

This docs set tracks CLI release 0.10.0. Docs updates land in lockstep with each release; if you're on an older CLI, some --mode / --target flags mentioned here won't be present yet — see the CLI index for what maps to what.

Extending the CLI? Fluid Forge ships three plugin extension points and a companion SDK on PyPI. If your team has its own CI templates, scaffolding standards, or governance rules, see SDK & Plugins.

Stuck on install? Jump to Troubleshooting further down, or open an issue — happy to help.

Understand the version numbers

You will see two different version concepts in the docs:

• fluid version reports the installed CLI release, such as 0.10.0
• fluidVersion inside contract.fluid.yaml selects the contract schema version, such as 0.7.5

Which fluidVersion a fresh scaffold emits depends on the path:

• fluid init --quickstart copies the customer-360 template verbatim, which is pinned at fluidVersion: 0.7.2.
• fluid init --discover, fluid forge, and fluid product-new go through the factory and emit fluidVersion: 0.7.5 — the latest bundled schema.

The CLI still accepts contracts with fluidVersion 0.4.0, 0.5.7, 0.7.1, 0.7.2, 0.7.3, 0.7.4, and 0.7.5 — run fluid version for the authoritative compatibility list.

Quickstart with fluid init

Create a local project:

fluid init my-project --quickstart
cd my-project

Then run the core workflow:

fluid validate contract.fluid.yaml
fluid plan contract.fluid.yaml
fluid apply contract.fluid.yaml --yes

Beyond dev — the 11-stage production pipeline

The commands above are the dev on-ramp. For production, Fluid Forge promotes an 11-stage pipeline with cryptographic plan-binding, explicit destruction gating, and supply-chain signing:

1. bundle → 2. validate → 3. generate-artifacts → 4. validate-artifacts
      → 5. diff (drift gate) → 6. plan → 7. apply → 8. policy-apply
      → 9. verify → 10. publish → 11. schedule-sync (Path A only)

See the 11-stage pipeline walkthrough for the full end-to-end flow and fluid generate ci for auto-generating a parameterised pipeline for Jenkins / GitHub Actions / GitLab / Azure DevOps / Bitbucket / CircleCI / Tekton.

What the quickstart gives you

The generated project includes a working contract plus local assets so you can validate and apply immediately. The exact scaffold evolves over time, but the important files are:

my-project/
├── README.md
├── contract.fluid.yaml
├── data/
└── .fluid/

Optional AI-assisted path with fluid forge

If you want the CLI to discover local context and scaffold with LLM help, use fluid forge instead of fluid init:

fluid forge
fluid forge --domain finance
fluid forge --llm-provider openai --llm-model gpt-4.1-mini

Use fluid init for the fastest deterministic quickstart. Use fluid forge when you want discovery, memory, or domain-guided scaffolding.

Promoted next commands

fluid test contract.fluid.yaml
fluid verify contract.fluid.yaml
fluid generate schedule --scheduler airflow
fluid publish contract.fluid.yaml

Compatibility note: fluid generate-airflow still exists, but the promoted orchestration path is fluid generate schedule --scheduler airflow.

Move to providers later

When you are ready to target a provider:

• GCP guide
• AWS guide
• Snowflake quickstart
• Provider overview

Troubleshooting

fluid: command not found

Try the module entry point:

python -m fluid_build.cli --help

Local quickstart dependencies look incomplete

Run:

fluid doctor --verbose

Unsure what to use next

Use the CLI help pages:

fluid --help
fluid <command> -h

Next steps

• CLI Reference
• Local walkthrough
• Vision

Need help?

• Questions or ideas? Start a GitHub Discussion
• Bug or unexpected behavior? Open an issue with what you ran and what you saw
• Want to contribute? See the contributing guide