Chapter 14 · CLI and Local Run

Chapter goals: Master the core usage of the flue CLI — local agent running, blueprint scaffold generation, and offline documentation browsing.

14.1 Installation and Command Overview

The CLI is provided by the @flue/cli package. It is not a build tool — local dev and production builds are handled by Vite (vite dev / vite build); the CLI only负责 scaffold, single-run, blueprints, and offline docs:

# Install in-project (recommended; flue init writes it as a devDependency)
npm install @flue/runtime @flue/cli

npx flue --help

flue <command>

Commands:
  flue init [dir]               Scaffold a Flue project (interactive: target + deployment)
  flue run <path>               Run an agent module locally: submit a message, stream output, print reply
  flue add [kind] [name|url]    Pull an integration blueprint implementation guide
  flue update <kind> <name>     Pull an updated blueprint for an existing integration
  flue docs [read|search]       Offline browse docs matching your installed version

v2 removed dev / build / new / deploy commands

From Flue 2.0, flue dev and flue build are handled by Vite (vite dev / vite build with the @flue/vite plugin); the old flue new merged into flue init's完整 project scaffold; flue deploy no longer exists (see生态 deployment guides per target). flue run also changed from "calling a built服务" to in-process direct execution of the agent module.

14.2 Running Agents Locally

Two paths for two场景:

# ① Dev HTTP service: Vite handles the dev server and HMR
npx vite dev          # Default http://localhost:5173; auto-loads .env

# ② Single-shot run: no server, no port; submit a message, print reply, exit
npx flue run src/agents/triage.ts --message "Triage all bug-labeled issues in the repo"

Common parameters (full list: flue run --help):

Parameter	Purpose
-m/--message	Required: the message text for this run
--id <conversation-id>	Resume the same session (sessions persist by ID)
--name <agentName>	Select one agent when the module exports multiple
--data '<json>'	Provide initial data (requires initialData schema on the agent)
--uid / --new	Send conditions: resume specified instance / only allow new
--json	Output a structured result envelope

Use vite dev for service development

vite dev is driven by the @flue/vite plugin: parses 'use agent' files, provides HMR — saving a changed useModel() or instruction text takes effect immediately. .env is auto-loaded by Vite's standard mechanism (shell-exported values take precedence). Note: neither the CLI nor vite dev执行 the providers registered in app.ts — when using module-level setProvider(), write it in the agent module.

14.3 Blueprints: Project Scaffolding

Flue 2.0's scaffold is统一 by flue init — one command生成 a complete runnable项目 skeleton (including flue.config.ts, package.json, src/app.ts, .env, sample agent etc.; it only writes files, does not install dependencies):

# Interactive scaffold (must explicitly pass --target; errors in non-TTY environments otherwise)
npx @flue/cli init my-bot --target node           # or --target cloudflare [--deploy]

cd my-bot && npm install
npx vite dev                                      # Local service dev
npx flue run src/agents/hello.ts -m "hi"          # Service-less smoke test

Generated典型 directory structure:

my-bot/
├── src/
│   ├── app.ts          # Route entry (required): mount agent routes
│   ├── agents/         # 'use agent' functions
│   │   └── hello.ts
│   ├── skills/         # SKILL.md skill packs
│   ├── tools/          # Type-safe tools
│   └── channels/       # Inbound event channels
├── flue.config.ts      # target: 'node' | 'cloudflare'
├── vite.config.ts      # Generated with --deploy
└── package.json

init vs add/update division

flue init负责新项目 scaffold; flue add [kind] [name|url] and flue update <kind> <name> pull a blueprint implementation guide for a specific integration (database, sandbox, Slack channel etc.) for your coding agent to参照落地 — neither command直接改 your business code. Run flue add without args to list all available blueprints.

14.4 Offline Docs

flue docs bundles官方 docs matching your installed version into the terminal — ideal for飞机上 or内网 work, and avoids the网页 docs drifting from your installed version:

# List all doc pages
flue docs

# Search a topic (outputs JSON results)
flue docs search "sandbox"

# Print a page as Markdown
flue docs read /docs/guide/sandboxes

# CI: validate agent files parse correctly (without actually calling the model)
flue run src/agents/triage.ts --dry-run

Credential check

flue run checks provider credentials before the first model call. Missing keys报错 explicitly rather than failing silently: Error: no credentials for provider "anthropic" — set ANTHROPIC_API_KEY

14.5 Debugging Tips

# Run with detailed logs; observe tool calls and model turns (logs go to stderr)
npx flue run src/agents/triage.ts --message "Triage issue #42" --verbose

# Specify the target when the module has multiple agents; output structured envelope
npx flue run src/agents/tasks.ts --name triage --json

# Resume a session (the second call sees the first's content)
npx flue run src/agents/triage.ts --id ticket-42 --message "Anything missed?"

Paired with the Chapter 13 observer, the full event stream is visible locally too:

// Mount a console observer only in local dev
if (process.env.NODE_ENV === 'development') {
  observe((event) => console.log(new Date().toISOString(), event.type));
}

14.6 Chapter Summary

• v2 CLI has five commands: init / run / add / update / docs;
• Dev and build are Vite'sjob: vite dev for HMR, vite build produces dist/server.mjs;
• flue run executes a single agent module in-process; stdout only outputs the reply, logs go to stderr — naturally CI-friendly;
• flue docs provides version-synced offline docs; blueprints are pulled via add/update.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What does flue run do differently from vite dev?

2. What is the purpose of flue add?

3. Why does flue docs provide version-synced offline docs?

4. What happens if you run flue run without setting the required API key?

🛠️ Hands-On Exercises

1. Run npx flue init my-bot --target node; verify the generated skeleton; run npx flue run src/agents/hello.ts -m "hi" and confirm the reply.
2. Run npx flue add without args; pick one integration blueprint and参照 it to add a tool to your project.
3. Run flue docs search "sandbox"; verify the results match your installed version.

CLI mastered. Next, Deployment: Node.js and Cloudflare Workers.