CLI Overview

Purpose and Scope

The Flue CLI is the day-to-day command surface for creating, developing, exercising, inspecting, and building a Flue application. It is intentionally positioned around the application lifecycle rather than around low-level model calls: a developer installs @flue/cli, starts a local runtime, runs individual agents or workflows through the same mounted application surface, and produces target-specific deployment artifacts. This page orients you to the command family and the development loop so you can choose the right command before reading the narrower command reference pages.

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

A useful way to think about the CLI is that it operates on a discovered Flue project, not on isolated scripts. The docs describe local development as serving the configured Node.js or Cloudflare target, watching source files, and rebuilding on changes. That matters because local development should resemble the eventual deployed application: authored routes, middleware, SDK-accessible HTTP endpoints, and resource mounts are all part of what you test. Discovery alone does not expose agents and workflows publicly; routing remains an authored decision.

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

The CLI also sits beside the client SDK rather than replacing it. The SDK overview describes @flue/sdk as the package applications use to consume deployed agents and workflows, with a createFlueClient(...) entrypoint and namespaces for agents, workflows, and runs. During development, flue dev gives you the real HTTP and SDK surface to connect against. In automation or production client code, the SDK becomes the programmatic consumer of the deployed application that the CLI helped build and test.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/sdk/overview.md

Relevant Source Files

• apps/docs/src/content/docs/cli/overview.md - Defines the reader-facing CLI overview, installation instructions, local development loop, one-resource execution behavior, build guidance, and command reference table.
• apps/docs/src/content/docs/sdk/overview.md - Defines the adjacent SDK framing used by CLI users when they test or consume the HTTP surface created by a local or deployed Flue application.

Installation and Runtime Requirements

Install the CLI as a development dependency and invoke it through your package manager. The documented quick path is to add @flue/cli and then run npx flue dev. The same source states that the CLI requires Node.js >=22.19.0, while Cloudflare development and deployment additionally require wrangler as a development dependency. Those requirements are part of the CLI contract because the command needs to launch or build the selected runtime target rather than merely transpile local TypeScript.

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

npm install --save-dev @flue/cli
npx flue dev

The repository itself is a monorepo, but the CLI overview is written for application authors rather than Flue contributors. You should treat the CLI as a project-local tool that reads your configuration and source layout, then performs target-aware work. In practice, this means you should install it in the application workspace, keep runtime-specific dependencies such as wrangler with the application when targeting Cloudflare, and prefer package-manager invocation so the command version matches the project that generated or built the application.

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

Development Loop

flue dev is the command for the inner loop. It serves the application for the configured Node.js or Cloudflare target, watches source files, and rebuilds on changes. The important detail is not just that it starts a server; it starts the application through the same kind of target-aware runtime surface that routes and integrations use. That lets you author application routes, channel integrations, agent mounts, workflow mounts, and SDK consumers against something close to the deployed shape.

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

npx flue dev

The CLI overview explicitly warns that agents and workflows are not public merely because they are discovered. Discovery makes resources available to the build and local tooling, but exposure is controlled through routing. This separation avoids a common mistake: assuming that a file under an agents or workflows directory automatically becomes a public endpoint. The development loop should therefore include route authoring and route testing, not just checking whether a resource file exists and compiles.

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

Because the SDK overview frames @flue/sdk around deployed Flue agents and workflows, the dev server becomes the bridge between authoring and consumption. You can test HTTP behavior with the same conceptual client shape used later in an application: configure a client with a base URL, invoke agents, start workflows, and stream events where the server exposes those capabilities. The CLI does not replace route design or client integration; it provides a local, watchable runtime where those decisions can be exercised safely.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/sdk/overview.md

Exercising a Single Resource

flue run is for a focused execution: run one agent prompt or one workflow invocation, then exit. The overview examples show both an agent-style resource name and a workflow-oriented task name. This command is useful when you want quick feedback on behavior without manually starting a long-lived dev server and writing a client call. It is still routed through the application model: the command calls through the authored app.ts and an existing flue() mount, so normal application and resource middleware executes.

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

npx flue run assistant --input '{"message":"Summarize this repository."}'
npx flue run summarize-ticket --input '{"ticket":"Ticket details"}'

Server selection is part of the command convention. Without an absolute --server, the command starts the configured Node.js or Cloudflare runtime temporarily. If your authored local mount is not at the root, you can use a path such as --server /api/flue. If you provide an absolute URL, the command attaches to an already-running local or deployed application. The overview also notes that route-free resources can be temporarily available through the mount for local use, but that behavior does not alter deployment behavior or create a public mount.

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

npx flue run workflow:summarize-ticket \
  --server https://example.com/api/flue \
  --input '{"ticket":"Ticket details"}'

This makes flue run a good smoke-test and debugging tool, but not a substitute for deployment configuration. Use it to verify prompts, workflow inputs, middleware assumptions, identity handling, headers, and resource qualification before you make the resource part of a public route. When the command points at an existing server, it becomes a convenient external exerciser of the same surface that SDK consumers would call. When it starts a temporary runtime, it keeps the test local while still respecting the configured target.

Sources: apps/docs/src/content/docs/cli/overview.md, apps/docs/src/content/docs/sdk/overview.md

Build, Deploy, and Target Awareness

flue build creates target-specific deployment output. The overview keeps the build responsibility narrow: it packages the discovered application for the runtime target. It does not choose a model, add credentials, expose additional routes, or configure platform-owned bindings. This boundary is important because it prevents the build command from becoming a hidden deployment policy engine. You use configuration, routes, target-specific deployment guides, and platform setup to make those decisions; the CLI packages what the project already declares.

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

npx flue build

The target distinction appears throughout the CLI overview. flue dev serves either a Node.js or Cloudflare target, and flue run can temporarily start the configured Node.js or Cloudflare runtime when you do not supply an absolute server URL. The same application source can therefore be exercised through different runtime assumptions, but the CLI does not erase target-specific requirements. For Cloudflare, the docs call out wrangler; for Node.js, deployment concerns are deferred to the Node deployment guide.

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

Build output should be considered the handoff point from Flue project discovery into platform deployment. If the application needs credentials, model provider configuration, route exposure, channel verification secrets, database bindings, or platform-owned resources, those are not invented by flue build. The command’s role is closer to packaging and generation than provisioning. That division makes builds repeatable and keeps sensitive or environment-specific decisions in configuration, environment variables, or the hosting platform.

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

Command Family Reference

The CLI overview lists seven commands. They form a compact command family that starts with project setup, supports local development and one-off execution, produces deployable artifacts, and keeps blueprint-based project assets current. Read the table as a map of intent rather than as complete syntax: each command has a dedicated reference page for options and edge cases, while this overview explains when to reach for each command in the overall workflow.

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

flue init belongs at the beginning of a project because it creates the initial configuration file. flue add and flue update are blueprint-oriented commands: they fetch installation or upgrade guidance for coding agents rather than silently mutating every part of an integration. That distinction matches Flue’s larger harness philosophy: application authors keep control over routes, credentials, tools, channels, database adapters, and runtime target decisions, while the CLI supplies structured commands and current project guidance.

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

CLI and SDK Boundary

The SDK overview explains that createFlueClient(...) configures access to a deployed Flue application and exposes API namespaces for client.agents, client.workflows, and client.runs. That framing helps clarify the CLI boundary. The CLI creates, serves, exercises, builds, and documents the application from the developer’s machine. The SDK is what external application code uses once a Flue HTTP surface exists. When you test an SDK consumer during development, flue dev can provide the local base URL.

Sources: apps/docs/src/content/docs/sdk/overview.md, apps/docs/src/content/docs/cli/overview.md

The SDK source also notes that deployment-wide listing is a server-side concern composed from runtime primitives rather than a built-in client-wide listing feature. That detail reinforces a recurring CLI rule: Flue does not make everything public or administrative by default. You author the server surface you want, then use the CLI and SDK against that surface. For CLI users, the next step is to read the command-specific pages for syntax, then read routing and SDK references before exposing production endpoints.

Sources: apps/docs/src/content/docs/sdk/overview.md, apps/docs/src/content/docs/cli/overview.md