flue add

Purpose and Scope

flue add is the Flue CLI command for discovering implementation blueprints and handing them to a coding agent. A blueprint is Markdown guidance for adding a new capability to a Flue project, such as a sandbox adapter, a verified HTTP channel, a database persistence adapter, or developer tooling. The important constraint is that flue add is not a package installer and not a file generator. It fetches instructions, then you or your coding agent review and apply those instructions in the project. Sources: apps/docs/src/content/docs/cli/add.md

This design matches Flue’s harness-first workflow. Flue projects are usually composed from application-owned code: agents define instructions, tools, skills, models, and sandboxes, while channels and adapters connect outside systems into the runtime. flue add helps a coding agent understand the conventions for those pieces without hiding the implementation behind an opaque scaffolder. The command is therefore useful when you want repeatable first-party guidance but still want the resulting module, SDK choices, verification logic, environment variables, and tests to remain visible in your repository. Sources: apps/docs/src/content/docs/cli/add.md

Use this page when you need to know what the command accepts, when to pass a known blueprint name instead of a URL, and how --print changes the output behavior. It is a CLI reference page, not a full channel, sandbox, database, or tooling guide. After choosing a blueprint, continue to the relevant guide or ecosystem page for implementation details, especially when the blueprint touches provider signatures, database transactions, observability export, or sandbox isolation boundaries.

Relevant Source Files

• apps/docs/src/content/docs/cli/add.md - Defines the public flue add documentation page, including synopsis, description, arguments, options, blueprint kinds, examples, and links to related implementation guidance.

Command Synopsis

The command has two public forms. Running it with no arguments lists known blueprints. Running it with a blueprint kind and a name or URL fetches a specific Markdown blueprint. The documented synopsis is intentionally small because the command is meant to route users to implementation guidance rather than perform project mutation itself. Sources: apps/docs/src/content/docs/cli/add.md

flue add
flue add <kind> <name-or-url> [--print]

The no-argument form is the discovery path. It is the safest first command when you do not know the exact slug or alias for a blueprint, because it lists the currently known blueprints instead of guessing. The two-argument form is the application path. In that form, <kind> selects the category of implementation work and <name-or-url> selects either a known blueprint slug or an absolute URL that becomes research input for a generic blueprint. Paths are explicitly not accepted, so local filesystem references are not part of this command’s contract. Sources: apps/docs/src/content/docs/cli/add.md

The URL behavior is important for providers that Flue does not already know by name. For example, if a webhook provider is not represented by a first-party channel blueprint, you can pass the provider’s public webhook documentation URL with the channel kind. Flue then fetches the generic channel blueprint and uses the URL as the coding agent’s research starting point. That keeps the command broadly useful while still preserving the distinction between known first-party integrations and custom provider work.

Arguments and Options Reference

The --print option is the main switch for automation and agent handoff. Without focusing on the terminal integration details, the documented behavior guarantees that --print emits raw Markdown to standard output. That makes the command composable with coding-agent CLIs: you can pipe the blueprint into tools such as Codex, Claude, or opencode, then let that agent inspect the current project and propose edits. Sources: apps/docs/src/content/docs/cli/add.md

Use --print when you want deterministic, copyable output, when you are scripting the command, or when you want to pipe the blueprint directly into another process. It is also the right choice for documentation review because it shows the actual Markdown implementation plan instead of relying on any coding-agent detection behavior. The command documentation emphasizes that this output is still only a blueprint; applying it remains a reviewable development task.

Blueprint Kinds

flue add organizes blueprints by implementation responsibility. A sandbox blueprint helps build a sandbox adapter from provider documentation or source. A channel blueprint adds verified provider ingress, a client, and application-owned tools. A database blueprint adds a database-backed persistence adapter. A tooling blueprint adds developer tooling such as observability or evaluation support. Sources: apps/docs/src/content/docs/cli/add.md

These categories map directly to parts of a Flue application that are deliberately project-specific. A sandbox controls where agents can run code or shell work, so its adapter must reflect the chosen provider’s isolation and lifecycle model. A channel receives inbound provider HTTP events, verifies them, preserves provider-native payloads, and routes them to application handlers. A database adapter backs durable state and must satisfy the runtime’s persistence expectations. Tooling integrations connect evaluation, telemetry, or error reporting systems without changing the agent contract itself.

The channel kind deserves special attention because it can be mistaken for an outbound provider SDK scaffold. In Flue terminology, channels are focused on inbound HTTP events. The application normally uses the provider’s established SDK for outbound calls, then exposes only the operations that agents or handlers need. A channel blueprint can guide creation of a module such as src/channels/slack.ts, but the resulting code should still make verification, handler behavior, and any application-owned tools explicit.

Usage Patterns and Examples

The shortest discovery command is simply flue add. Run it before choosing a known blueprint if you need the current catalog. Once you know the kind and slug, pass both arguments and usually add --print so the Markdown can be reviewed or piped into a coding agent. Sources: apps/docs/src/content/docs/cli/add.md

flue add
flue add sandbox daytona --print
flue add sandbox daytona --print | claude
flue add channel github --print | codex
flue add channel slack --print | codex
flue add database postgres --print | codex
flue add tooling braintrust --print | opencode
flue add tooling sentry --print | opencode
flue add tooling vitest-evals --print | opencode

Known blueprint examples cover channel providers such as GitHub, Stripe, Notion, Resend, Shopify, Intercom, Zendesk, Salesforce Marketing Cloud, Slack, Discord, Teams, Google Chat, Linear, Telegram, WhatsApp, Twilio, and Messenger. The examples also include sandbox blueprints such as Daytona and @cloudflare/shell, database work such as Postgres, and tooling integrations such as Braintrust, Sentry, and Vitest evals. Treat the example list as a guide to supported names in the documentation, then run the no-argument command if you need the live list exposed by the installed CLI. Sources: apps/docs/src/content/docs/cli/add.md

For providers outside the known catalog, use an absolute documentation URL instead of a name. The documentation shows generic URL patterns for sandbox, channel, database, and tooling blueprints. This is useful when your coding agent needs provider-specific research material but you still want Flue’s conventions for module discovery, verification, adapter contracts, or tooling shape to frame the implementation.

flue add sandbox https://e2b.dev --print | claude
flue add channel https://provider.example/webhooks --print | codex
flue add database https://database.example/docs --print | codex
flue add tooling https://tool.example/docs --print | opencode

Execution Flow

A typical workflow starts with discovery, continues with blueprint retrieval, and ends with reviewed project changes. First, run flue add to list known blueprints or choose a documented example directly. Second, run flue add <kind> <name-or-url> --print so the command emits Markdown. Third, send that Markdown to your coding agent or read it yourself. Fourth, let the agent inspect your project layout, create or update modules, install packages when appropriate, and add tests or configuration changes. The last four actions are not performed by flue add itself; they are implementation work guided by the blueprint. Sources: apps/docs/src/content/docs/cli/add.md

This separation is a practical safety boundary. Because the command does not write files, it cannot silently add route handlers, change persistence behavior, or introduce provider secrets. Instead, it produces a plan that can be compared against the project’s existing Flue structure. For a channel, that may mean checking route placement and signature verification. For a database adapter, it may mean checking transaction support and durable store behavior. For tooling, it may mean deciding where instrumentation is registered and what content is exported.

When using an absolute URL, review the generated work especially carefully. The URL becomes a research starting point, not a guarantee that the resulting implementation is correct for production. Provider webhook documentation often includes handshake events, signature formats, timestamp tolerances, raw-body requirements, retry semantics, and response expectations. A useful implementation should preserve provider-native payloads and test both valid and invalid requests. The blueprint can direct the coding agent toward those concerns, but application maintainers remain responsible for validating the final code.

When to Use Related Guides

After flue add returns a blueprint, continue with the concept or ecosystem guide for the resource you are adding. The command documentation links readers to the Sandboxes guide, the Channels guide, and the Ecosystem area for implementation guidance. Sources: apps/docs/src/content/docs/cli/add.md

Choose the Sandboxes material when the blueprint affects execution isolation, file access, shell commands, or remote container lifecycle. Choose the Channels material when the work receives provider HTTP events and connects them to an agent, workflow, or application handler. Choose database guidance when the work changes persistence for durable execution. Choose tooling guidance when the work exports observability data, configures evaluation, or integrates an external developer platform.

A good next step is to run the command with --print, save or inspect the Markdown, and ask your coding agent to apply it in a small reviewable change. Keep the resulting implementation narrow: add the integration module, wire it into the Flue app where required, add any environment variables, and test the behavior that the provider or adapter depends on. For broader context, read the CLI overview before automating command usage, and read the relevant guide page before deploying the generated integration.