flue run

Purpose and Scope

flue run is the CLI command for exercising one Flue resource from a terminal: either an agent prompt or a workflow invocation. It is useful when you want the same application behavior that an HTTP caller would receive, but without writing a separate client, manually starting a server, or deploying the project first. The command discovers a resource by name, sends JSON input, streams activity as the run progresses, prints the terminal result, and exits. In practice, it is the fastest way to verify that an authored agent or workflow is wired correctly before moving on to browser, channel, or production integration work.

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

The important design point is that flue run is not a shortcut around application composition. When it starts a temporary local runtime, the authored app.ts, outer middleware, and resource middleware still run as they would for a normal HTTP request. Route-free discovered resources are made available through an existing authored flue() mount, but the command does not create a mount, rewrite metadata, or change deployment output. That means command-line testing remains representative of the application boundary your users and integrations will actually call.

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

Relevant Source Files

• apps/docs/src/content/docs/cli/run.md — Defines the public CLI reference for flue run, including synopsis, runtime behavior, resource naming, input shape, identity handling, server selection, headers, and project options.

Synopsis and Command Shape

The reference synopsis shows flue run taking a resource name plus optional flags for target runtime, identity, input, server routing, headers, root, output, config, and environment file selection. The <name> argument is the resource selector, while --input carries the JSON payload for the invocation. The target-related options are only relevant when the command is responsible for starting a temporary local runtime. If the command is pointed at an absolute server URL, it attaches to that already-running application instead of performing local discovery, build, or startup.

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

flue run <name> [--target <node|cloudflare>] [--id <id>] [--input <json>] [--server <path|url>] [--header 'Name: value'] [--root <path>] [--output <path>] [--config <path>] [--env <path>]

Use the command when you need a single, observable invocation rather than a long-running development server. For example, a developer can run an agent prompt while editing instructions, or trigger a workflow with representative JSON while checking how middleware and persistence behave. Because the command streams activity and prints the final result, it fits both interactive debugging and scripted verification. The command is intentionally scoped to one invocation: it is not a replacement for a deployed endpoint, a channel listener, or a full development loop.

Resource Names

The <name> argument can identify either an agent or a workflow. If an agent and workflow share the same name, qualify the selector with agent: or workflow: so the command can resolve the intended resource unambiguously. This qualification is also required when using an absolute --server URL, because in that mode no local project is available for discovery. A remote or already-running application can receive the request, but the CLI cannot infer whether an unqualified name should be interpreted as an agent or a workflow from local files.

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

flue run agent:report --input '{"message":"Prepare the report."}'
flue run workflow:report --input '{"period":"week"}'

Treat the name selector as part of the command's contract with your project layout. In local mode, discovery can resolve authored resources, then the temporary runtime calls them through the normal application. In server mode, the server URL is the application boundary and the qualified selector becomes the portable way to describe what should run. This distinction matters for automation: local scripts can use unqualified names when no collision exists, while scripts that target shared or deployed environments should prefer explicit agent: or workflow: selectors.

Input and Identity

Agent input has a specific prompt-oriented shape. The --input flag is required for agents and must include a message string. That message is delivered as a user message to the agent, matching the public prompt body rather than an internal runtime structure. The input may also include an images field containing attachments with { type: "image", data, mimeType }. This keeps command-line prompts aligned with the agent API surface while still supporting multimodal prompts when the selected model and application configuration allow them.

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

{ "message": "Summarize the open issues." }

Agent identity is controlled with --id. When omitted, Flue generates and displays a bare ULID for the persistent agent instance. Supplying an ID lets you resume the same agent instance across invocations, but only when the configured persistence adapter survives the temporary process. This caveat is important in local experimentation: an ID alone is not durable state. Durable continuity depends on the persistence configuration behind the application, so ephemeral storage will not preserve the previous conversation just because the same ID is reused.

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

Workflow input is intentionally simpler. The JSON passed through --input is parsed and delivered unchanged to the workflow. It may be omitted when the workflow accepts omitted input. Unlike agents, workflows do not support --id; they use generated run IDs. This reflects the difference between a continuing agent instance and a workflow run. Agents can have persistent identity across prompts, while workflows represent structured executions that produce their own run identity as part of invocation.

Server Selection, Routes, and Headers

The --server flag selects the Flue base URL. When the value is a path, the command starts a temporary local runtime and points the SDK at that authored flue() mount. When the value is an absolute URL, the command attaches to an existing local or deployed application. In absolute URL mode, local configuration, discovery, build, and startup are skipped. This lets the same command family test both local project resources and deployed applications, while preserving the route structure the application author chose.

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

flue run summarize --server /api/flue --input '{"text":"hello"}'
flue run workflow:summarize --server https://example.com/api/flue --input '{"text":"hello"}'

--server does not create, move, or alter routes. If the path is wrong, the request receives the application's normal response. That behavior is useful because it exposes routing mistakes instead of hiding them behind CLI-specific behavior. A successful local invocation demonstrates that the authored mount exists and that middleware admits the request. A failed invocation against a wrong path should be investigated like any other application routing issue: check the mounted base path, the selected resource name, and any middleware that may reject the request.

Headers are supplied with repeated --header flags. They are sent on admission, stream reads, and reconnects, which matters for authenticated applications and middleware that validates every request in a streaming session. Use headers for authorization tokens or application context that would normally accompany the HTTP caller. If the same header name is repeated, the final value wins case-insensitively. This rule keeps command behavior deterministic when scripts compose default headers with per-run overrides.

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

flue run report --header 'Authorization: Bearer ...'

Project Options Reference

The project-oriented options control how a temporary local runtime is selected and configured. --target <node|cloudflare> chooses the runtime target for the temporary local process, defaulting to the configuration value when not provided. --root <path> selects the project root; the documented default is the selected config-file directory or the config search directory. --output <path> defaults to <root>/dist and configures deployment build output, while the reference notes that temporary Node execution does not write runtime artifacts there. The synopsis also includes --config <path> and --env <path> for selecting configuration and environment inputs.

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

A useful workflow is to start with a local path server when validating application composition, then move to an absolute URL when checking a deployed or separately running application. Keep inputs small and representative, qualify names in scripts, and pass the same authentication headers your real callers use. If you are debugging agent continuity, record the generated ULID or provide --id, then confirm that the selected persistence adapter actually survives the temporary runtime. For broader context, read the CLI overview, the agent API, and the workflow API next.