flue build

Purpose and Scope

flue build is the command that turns an authored Flue project into deployment output. In day-to-day development, Flue projects are organized around source files that define agents, workflows, and optionally an application entrypoint. The build command is the point where those files are discovered under a chosen source root and converted into a target-specific artifact. This matters because Flue is not only a local authoring framework: the same project can be prepared for a Node.js server deployment or a Cloudflare Workers deployment, depending on the selected target.

Sources: apps/docs/src/content/docs/cli/build.md

Use this page when you need a command reference for production or preview builds, when you are wiring build scripts in a package manager, or when you are trying to understand which flags control the root, configuration file, environment file, output location, and target runtime. It intentionally focuses on the public command contract documented for users: the synopsis, option defaults, generated output expectations, and the distinction between Node.js and Cloudflare builds. For source discovery conventions, the command documentation points readers to the Project Layout guide rather than repeating those rules in the build reference.

Relevant Source Files

• apps/docs/src/content/docs/cli/build.md - First-party documentation source for the flue build command, including synopsis, description, options, target outputs, and examples.

Command Synopsis

The documented invocation shape is concise: flue build [--target <node|cloudflare>] [--root <path>] [--output <path>] [--config <path>] [--env <path>]. The target flag selects the deployment runtime, while the remaining flags control how the command finds project files and where it writes the result. If a project already has configuration that supplies the target, the target flag does not need to be repeated; otherwise, the build target is required. This design lets teams choose between explicit command-line invocations and reusable project-level configuration.

Sources: apps/docs/src/content/docs/cli/build.md

The command discovers agents, workflows, and an optional application entrypoint under the selected source root. In Flue terminology, agents are durable programmable resources that can be exposed and deployed, while workflows are structured automations that can run alongside them. The build command treats those public project resources as the deployment surface. It is therefore not a generic TypeScript compilation command; it is a Flue-aware packaging step that knows which application resources need to be collected for the chosen runtime target.

Options Reference

The build reference documents five user-facing options. --target <node|cloudflare> selects the target runtime and defaults to the configuration value when present. --root <path> selects the project root and defaults either to the selected config-file directory or to the directory used for config search. --output <path> selects the output directory and defaults to <root>/dist. --config <path> selects a configuration file and otherwise relies on auto-discovery of flue.config.*. --env <path> selects an alternate .env-format file loaded before configuration.

Sources: apps/docs/src/content/docs/cli/build.md

The environment-file behavior is worth calling out because it affects reproducible builds. The documented default is <config-base>/.env when that file is present. If an alternate path is supplied, relative paths resolve from <config-base>, not necessarily from the shell’s current working directory. The docs also state that shell values win, so values already present in the process environment take precedence over values read from the dotenv file. That ordering lets CI systems inject secrets or deployment-specific values without editing a local .env file.

Compact option reference

• --target <node|cloudflare>: Selects the build target. Required unless supplied by configuration.
• --root <path>: Selects the project root used for discovery and output defaults.
• --output <path>: Selects the build output directory. Defaults to <root>/dist.
• --config <path>: Selects a configuration file instead of relying on auto-discovered flue.config.*.
• --env <path>: Loads one alternate .env-format file before configuration; relative paths resolve from <config-base>, and shell values win.

Build Workflow

A typical build starts by deciding the project root and configuration source. If --config is supplied, the command uses that file; otherwise it auto-discovers a flue.config.* file. The chosen configuration base then influences defaults such as .env loading and the selected root. After configuration and environment values are resolved, the command discovers project resources under the selected source root. The public documentation specifically names agents, workflows, and an optional application entrypoint as the resources collected for build output.

Sources: apps/docs/src/content/docs/cli/build.md

Once discovery is complete, the command writes target-specific deployment output. That target-specific step is the reason flue build has a runtime target rather than a single universal artifact. A Node.js deployment expects a runnable server module, while a Cloudflare deployment expects Workers-compatible application files that can participate in Cloudflare’s build and deployment tooling. The command reference deliberately separates those outputs so that users know what to look for after the build finishes and which deployment guide to consult next.

The build command is also the boundary between authoring layout and hosting concerns. During authoring, a project may contain agent files, workflow files, configuration, skills, tools, and route code. During deployment, the runtime needs an artifact that can be started by the chosen host. flue build bridges those concerns without asking the user to manually assemble generated entries. The docs describe the command in terms of discovery and deployment output, which is the right mental model for debugging: first confirm the command is looking in the intended root, then confirm it is building for the intended target.

Target Outputs

For the Node.js target, the documented output is a runnable server artifact at <output>/server.mjs. Because --output defaults to <root>/dist, a default Node build commonly produces a server module in the project’s distribution directory. The command reference does not describe that file as a library bundle; it describes it as a server artifact. That wording is important for deployment planning because the next step is to run or deploy the generated server with the runtime dependencies expected by the Node.js deployment guide.

Sources: apps/docs/src/content/docs/cli/build.md

For the Cloudflare target, the command writes a Workers-compatible application through the official Cloudflare Vite integration. The reference says Flue prepares generated Worker and Wrangler input files, but does not rewrite the project’s authored Wrangler configuration. That means the build step participates in Cloudflare’s expected toolchain while preserving project-owned deployment configuration. In particular, Durable Object migration history remains in the project-root Wrangler config and passes through unchanged, so migration history should continue to be managed in the Wrangler configuration rather than treated as generated build state.

The Node.js and Cloudflare targets therefore differ in both artifact shape and configuration ownership. Node.js output is described as a single runnable server module, while Cloudflare output is described as generated input for a Workers-compatible application using the Cloudflare Vite integration. When troubleshooting, use that distinction to avoid looking for the wrong file. A Node build should make <output>/server.mjs the key artifact, while a Cloudflare build should be evaluated in terms of the generated Worker and Wrangler inputs plus the unchanged project-root Wrangler configuration.

Examples

The documented examples cover the most common usage patterns. flue build --target node builds for the Node.js target using discovered configuration and default output placement. flue build --target cloudflare --root ./my-app builds a Cloudflare artifact from a specific project root, which is useful from a workspace or parent directory. flue build --target node --output ./build keeps the Node target but overrides the output directory. These examples are small, but together they show the two most important axes: target selection and filesystem selection.

Sources: apps/docs/src/content/docs/cli/build.md

flue build --target node
flue build --target cloudflare --root ./my-app
flue build --target node --output ./build

When adding this command to automation, prefer making the target explicit unless your project configuration is the single source of truth for builds. An explicit target makes CI logs easier to read and avoids ambiguity when the same repository contains examples or packages aimed at different deployment environments. If the root is not the current working directory, pass --root so discovery happens in the intended project. If your deployment system expects artifacts in a non-default directory, pass --output rather than moving generated files after the fact.

Practical Checks and Next Steps

After a build, check the output that corresponds to the selected target. For Node.js, verify that the configured output directory contains server.mjs. For Cloudflare, verify that the build produced Workers-compatible generated input while preserving the authored Wrangler configuration in the project root. If environment-sensitive values are involved, confirm whether they came from the shell, the default .env, or an alternate file passed with --env. Because shell values win, unexpected CI environment variables can explain differences between local and remote build results.

Sources: apps/docs/src/content/docs/cli/build.md

Read the Project Layout page next when a build appears to miss an agent, workflow, or application entrypoint, because discovery rules are intentionally delegated there. Read the Node Target or Cloudflare Target pages when you need runtime-specific deployment behavior beyond the command synopsis. For command-family context, the CLI Overview explains how flue build fits with local development, running resources, initialization, add/update workflows, and generated project assets. For application authors, the main habit is simple: define resources in the documented layout, choose a target, and let flue build create the deployment artifact for that runtime.