flue init

Purpose and Scope

flue init is the Flue CLI command for creating the first project configuration file in an existing directory. Its job is deliberately small: it writes a starter flue.config.ts that selects a runtime target, then leaves the rest of the application structure to the developer. This makes the command useful when you already have a package, repository, or workspace directory and want to mark it as a Flue project without scaffolding agents, workflows, channels, database adapters, or a custom application entrypoint.

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

Use this command when the immediate task is configuration, not full application generation. A Flue project can contain addressable agents, durable workflows, verified channels, persistence wiring, and routing code, but flue init does not attempt to infer or create those surfaces. The generated file establishes the target that later commands and build behavior use. After initialization, you add source files such as src/app.ts, src/agents/, or src/workflows/ according to the project layout and the runtime target you chose.

The command is especially important because the selected target changes how a Flue application is built and run. The documented target choices are node and cloudflare. Choosing node prepares the configuration for a Node-target Flue application, while choosing cloudflare prepares it for Cloudflare-oriented builds and runtime behavior. flue init records only that target choice in the initial file, so it is safe to treat the output as a minimal starting point rather than a complete production configuration.

Synopsis

The documented command shape is concise and required-target driven:

flue init --target <node|cloudflare> [--root <path>] [--force]

The --target option is required because the generated flue.config.ts must contain a target value. The optional --root option controls where the file is written, and the optional --force flag controls whether an existing supported configuration filename blocks generation. This combination supports both the common case of initializing the current working directory and the monorepo case of initializing a nested application directory from elsewhere in the repository.

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

A useful way to read the synopsis is that flue init never searches for a destination to create for you. The --root value is described as selecting an existing directory. That means the command is a configuration writer for a location you already control, not a project-directory generator. If you want a nested app such as ./apps/assistant, create or keep that directory as part of your normal workspace structure, then point flue init at it with --root.

Options Reference

The option contract is small enough to memorize, but each option affects a different safety boundary. --target <node|cloudflare> is required and selects the value written into the generated configuration. --root <path> defaults to the current working directory and changes the directory in which flue.config.ts is written. --force defaults to false and allows writing a new flue.config.ts even when another supported flue.config.* file already exists.

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

Compact reference:

The most important operational detail is the collision rule. Without --force, any existing flue.config.* file prevents generation. This protects a project from accidentally replacing or shadowing configuration during repeated setup attempts. With --force, the command can write flue.config.ts even beside another supported variant. The existing file remains on disk, but the new .ts file takes precedence. Treat --force as an explicit decision to make flue.config.ts the active configuration file in that directory.

Generated Output

The generated output is a minimal TypeScript configuration module. For flue init --target node, the documented file imports defineConfig from @flue/cli/config and exports the result of defineConfig({ target: 'node' }). The generated target value matches the value passed to --target, so the same shape applies to a Cloudflare initialization with target: 'cloudflare'. The command does not add extra source roots, database settings, route definitions, or package scripts.

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

import { defineConfig } from '@flue/cli/config';
 
export default defineConfig({
  target: 'node',
});

This minimal output is intentional because the configuration file is the stable handoff point between initialization and later authoring work. Starting from a tiny file makes the first configuration easy to inspect, review, and edit. It also avoids implying that every project needs the same agents, workflow names, persistence adapter, or channel setup. Once the target exists, developers can extend flue.config.ts using the complete configuration surface instead of reverse-engineering generated boilerplate.

Execution Flow

A typical initialization flow starts by deciding where the Flue application lives. In a single-package repository, run the command from the project root and omit --root. In a monorepo, choose the existing app directory and pass it explicitly. Then choose the target that matches the intended runtime. For a local server or Node deployment path, choose node. For a Cloudflare Workers-oriented application, choose cloudflare. The command writes the starter config and stops there.

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

Example commands:

flue init --target node
flue init --target cloudflare --root ./apps/assistant

After the file is generated, the next step is authoring application surfaces. Because flue init does not create agents, workflows, or an application entrypoint, a new project still needs source files before it does useful agent work. Add the Flue resources that match the application: agents for durable conversational work, workflows for structured finite operations, channels for verified ingress from external systems, and optional routing or database files when the project needs custom behavior. The init command gives later CLI commands a target-aware configuration to read.

The collision behavior should also shape day-to-day usage. If initialization fails because a supported flue.config.* file already exists, inspect that file before rerunning. In many cases, the project is already initialized and should be edited rather than regenerated. If the goal is to replace precedence with a new TypeScript config, rerun with --force and then compare the old configuration variant with the new flue.config.ts. The old file remains on disk, so cleanup is a separate maintenance step.

Relevant Source Files

• apps/docs/src/content/docs/cli/init.md — Defines the public flue init reference, including synopsis, command description, option defaults, collision behavior, generated flue.config.ts output, and example invocations.

System-to-Code Mapping

The public contract for flue init is represented as documentation in apps/docs/src/content/docs/cli/init.md. That source makes three boundaries clear. First, initialization is configuration-only: the command writes a starter flue.config.ts and does not create agent, workflow, or application entrypoint files. Second, the target is explicit and required, which prevents a project from being initialized without declaring whether it is for Node or Cloudflare. Third, file overwrite behavior is conservative by default and only changes when --force is supplied.

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

For developers maintaining docs or building adjacent tooling, those boundaries are the compatibility points to preserve. A wrapper, template, or internal bootstrap command can call or mimic flue init, but it should not surprise users by silently overwriting existing configuration or by implying that the generated file is a complete application. If additional scaffolding is desired, keep it as a separate step layered after the configuration write so the documented flue init behavior remains predictable.

Next Steps

After running flue init, open the generated flue.config.ts and confirm the selected target. Then add the application source files required for your project: an agent module if you are building an autonomous assistant, a workflow module if you are building a structured operation, a channel module if external provider events should enter the system, or an application entrypoint if you need custom routes and middleware. Use the Configuration reference when you need to extend beyond the initial target field.

Related pages to read next are configuration-reference for the complete flue.config.ts surface, project-layout for the files Flue discovers, cli-dev for the local development loop, and cli-build for target-specific builds. If you are still choosing between node and cloudflare, read the target-specific CLI pages before committing the generated config to a shared repository.