flue update

Purpose and Scope

flue update is the maintenance command for Flue integrations that were created from blueprints. A blueprint is a Markdown guide used to scaffold an integration such as a channel, sandbox, database adapter, or tooling package. The command retrieves the current form of that blueprint so a coding agent can compare it against the project’s existing implementation and apply the appropriate changes. It is intentionally not an auto-rewriter: the documented contract says that flue update fetches the same complete, current Markdown blueprint as flue add, and does not edit project files itself.

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

This command fits Flue’s harness-first workflow. Flue projects often contain durable agent resources, channel webhooks, sandbox adapters, database persistence, and observability tooling. Those integrations may include provider-specific signatures, deployment details, and local customizations. A blind file replacement would risk losing those choices. flue update instead supplies the latest blueprint material, then expects a coding agent to reason over the existing code, preserve local modifications, and make only the relevant changes. That separation is part of the command’s public behavior, not an implementation detail.

The shortest mental model is: flue add helps introduce a blueprint-backed integration, while flue update helps refresh one. Both can return raw Markdown, but flue update adds update semantics around version markers and URL-based research. The command is useful when Flue publishes a new blueprint version, when an integration was copied without a marker, or when a provider’s public documentation has changed and the project needs a fresh comparison point. In all cases, the human or coding agent remains responsible for applying edits to the repository.

Relevant Source Files

• apps/docs/src/content/docs/cli/update.md - Defines the public flue update reference page, including synopsis, description, marker semantics, arguments, options, and examples.

Command Synopsis

The documented command shape is compact and positional. It accepts a blueprint kind, then either a known blueprint name or an absolute URL. The optional --print flag changes the output mode so the raw Markdown blueprint is written to standard output. The synopsis is:

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

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

<kind> selects the blueprint family. The documented kinds are sandbox, channel, database, and tooling. These names match the kinds of integrations Flue expects users to maintain around an agent application: sandbox execution environments, verified channel ingress, persistence adapters, and ecosystem tooling. <name-or-url> is either a known blueprint slug or alias, such as a provider integration name, or an absolute URL used as a research starting point. The distinction matters because named blueprints can have Flue-maintained version history, while arbitrary URL updates do not necessarily have provider-specific versioned diffs.

The command’s most important option is --print. When present, the CLI writes the raw blueprint Markdown to standard output, matching the flue add behavior documented on the page. This makes the command composable with coding-agent CLIs and shell pipelines. For example, a developer can pipe the blueprint directly into a coding agent and ask it to apply the update. Without --print, the command still fetches the blueprint for update use, but the reference page emphasizes the raw Markdown behavior because that is the stable handoff format for agent-assisted maintenance.

Blueprint Markers and Update Modes

Most generated integrations contain a primary generated file with a version marker. The documented marker format is a TypeScript-style comment:

// flue-blueprint: kind/name@N

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

The marker records the blueprint kind, blueprint name, and version number that produced the integration. It gives the coding agent a durable anchor for safe incremental updates. When a named update has a marker, the agent should apply each cumulative, versioned unified diff after the marked version in ascending order. That ordering is important because later diffs may assume earlier blueprint changes have already been applied. The agent also preserves customizations and updates the marker after applying the relevant changes.

A named update without a marker uses a different strategy. The agent cannot rely on version history from a known starting point, so it inspects the existing implementation and compares it against the complete current blueprint. It then applies every relevant change while preserving customizations. If the blueprint has a primary marked file, the agent adds the current marker after the comparison-based update. If the blueprint has no primary marked file, the durable path remains comparison; the agent should not invent a marker in an auxiliary or deployment file.

A URL update is broader and more research-oriented. The CLI returns the refreshed generic blueprint with the URL as a starting point. It does not compare files and does not edit the implementation. Because there is no provider-specific Flue version history for an arbitrary URL, the agent compares the current implementation with the complete generic guide, the provider’s current primary source, and the current Flue contract. It then infers and applies only relevant changes. A marker is added or updated only when the guide defines a primary marked file.

Reference

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

The reference table is best read as a workflow contract rather than a low-level API specification. flue update produces the material needed for an update, but the update decision is contextual. Local projects may have authentication wrappers, route prefixes, custom persistence choices, or provider-specific edge cases that a blueprint cannot safely overwrite. The command therefore favors a Markdown handoff that a coding agent can combine with repository inspection. This is especially aligned with Flue’s documented use of coding agents for autonomous development work.

Execution Flow

A typical named update begins by identifying the integration kind and slug. If the project has a Slack channel integration created from a Flue blueprint, the developer can run flue update channel slack. The fetched blueprint represents the current complete guide for that integration. The coding agent should then locate the primary generated file, read the marker if one exists, and decide whether it can apply versioned diffs or must fall back to comparison. The user should review the resulting code changes because the command itself has not modified files.

For agent-assisted maintenance, --print makes the command explicit and scriptable. The documented examples show flue update sandbox daytona --print | codex and flue update channel https://provider.example/webhooks --print | claude. These examples demonstrate two important patterns: named blueprint updates can be streamed directly to an agent, and URL-based updates can provide research context for integrations outside the known blueprint catalog. In both cases, the receiving agent needs access to the project files to perform a meaningful comparison and preserve local behavior.

flue update channel slack
flue update sandbox daytona --print | codex
flue update channel https://provider.example/webhooks --print | claude

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

When using a URL, treat the output as guidance rather than authoritative provider-specific migration history. The docs explicitly say the CLI returns a refreshed generic blueprint with the URL as a research starting point. That means the agent should inspect the current provider documentation or primary source represented by the URL, compare it with the existing implementation, and align the result with the current Flue contract. This is useful for webhooks or integrations where Flue can provide the harness pattern but cannot know every provider’s versioned migration path.

Practical Guidance

Use flue update when an integration exists and you want to reconcile it with the latest Flue blueprint guidance. Do not use it as a replacement for project review. The command’s design assumes that generated code may have been customized after creation, and the documented update modes repeatedly emphasize preserving those customizations. Before accepting changes from a coding agent, inspect provider secrets, route names, verification logic, deployment files, and any application-specific behavior that was intentionally added after the original blueprint was installed.

For marker-based integrations, keep the marker in the primary generated file unless the blueprint’s instructions say otherwise. Removing the marker forces future updates into a comparison-based path, which can still work but loses the benefit of ordered cumulative diffs. Conversely, do not create markers in auxiliary files when the blueprint does not define a primary marked file. The docs call this out because an invented marker can imply a versioned update path that does not really exist, making later maintenance less reliable.

After running the command and applying changes, test the integration in the same surface where it is used. A channel blueprint should be checked against verified ingress routes and provider payloads. A sandbox blueprint should be checked against the execution environment it configures. A database blueprint should be checked against durable state behavior. A tooling blueprint should be checked against its instrumentation or developer workflow. flue update supplies the updated recipe, but correctness comes from applying that recipe to the concrete Flue application and validating the result.

Next Steps

If you are introducing an integration for the first time, read flue add before using this command, because flue update assumes there is an existing implementation to compare. If you are maintaining a generated project, combine this page with the project layout guidance so the coding agent knows where Flue discovers application surfaces such as app.ts, db.ts, agents/, workflows/, and channels/. For deployment-specific updates, also review the relevant target documentation before accepting generated edits.

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