CLI and MCP command reference

Invocation and root resolution#

Use this machine’s stable launcher; shell commands below use flux as shorthand:

flux <verb> [args] [--flags]

flux version reports the version, commit and entry point. If help and a documented flag disagree, identify the installation with config / connect_doctor; a source checkout may need npm run build:cli. Do not silently switch installations.

Project CLI verbs resolve --root → FLUX_PROJECT → cwd. Working from the project is convenient, but not required. A leading positional root remains supported where unambiguous (list /path/to/project, render-figure . growth). Machine/file verbs such as config, validate-plot and rerun-plot do not require a project.

Path rule: CLI filesystem inputs resolve from shell cwd, even with --root. MCP inputs resolve from the project default. Absolute paths work on both surfaces. Document/folder identifiers remain project-relative model identifiers. A shell glob expands before Flux sees it; compose-figure plots/*.svg requires the intended cwd. MCP binding and per-call project details are below.

Identity is detected from the agent environment/MCP handshake. FLUX_CLIENT is an optional journal/lock identity override, not a required session role. A CLI connect does not set cwd or environment for subsequent commands.

Connection protocol#

flux connect [<project>|global] [--live] [--refresh] [--depth core|full] [--no-render] [--json]

Agents invoke this when asked for flux-connect. An omitted target finds the project around cwd; a path may name the project or a directory inside it. Global mode reads machine context and lists known projects, preserving an existing MCP project binding.

The brief is the reading plan (at most 10,000 characters). Read FLUX.md, CONNECT.md, then the bundle and named images. Core depth includes ProjectContext and immediate links, Rules, recent Log and its title index, a project map, open items/activity and canvas overviews. Full depth adds all documents, individual figures and deck sheets. --no-render omits images; say so in the receipt. --json returns structured pack metadata; it is not a substitute for reading the brief/bundle.

Check every section-end marker and the final sentinel. If a tool truncated the middle or end, read smaller parts until complete. Use read_pack {packId,section:"brief"}, read_pack {packId,section:"A"} (the brief lists section IDs), or sequential read_pack {packId,part:1} calls. Parts are at most 20,000 characters; advance part until the bundle is complete. View images with get_pack_image {packId,index:0} (0-based), or open the printed PNG paths. A stdout-only fallback prints the exact connect --part … --pack … --sources … command to use; keep its source digest.

Return the brief’s receipt shape using only what you read and saw. Proof codes are at bundle section ends and image corners, not in the brief. Never invent them. flux connect --check-receipt <packId> "<proof line>" checks coverage; MCP uses connect_doctor {checkReceipt:{packId,proof:"<proof line>"}}. Report missing sections, trimmed material, unavailable renders and template ProjectContext honestly, then wait.

A “↻ Since you last looked” line on MCP results, and the Claude Code prompt hook, reports external changes during a connected session. read_delta {} reads details and advances the cursor; it can include new canvas images. connect --refresh (or MCP connect {refresh:true}) produces a refreshed pack and change summary. Read relevant changes before acting. Refresh does not authorize new work or watching.

Verb reference#

Figure 3D models#

Live dispatch_command also takes set_model_view and set_model_field (camelCase parameters, target or the current selection) as one Undo step. Posters, --no-poster, --state rules and the deck refusal: “3D model panels” in the FluxContext manual’s PROJECT-AND-FIGURES.md.

Slide commands#

--curve accepts the grammar and catalog names in animation curves: spring(0.35[, v=2]), spring(k=170,c=26,m=1), bezier(x1,y1,x2,y2) / cubic-bezier(...), steps(n[,start|end]), or standard, smooth, enter, exit, linear, gentle, overshoot, anticipate, anticipate + overshoot, settle, snappy, bouncy, playful, steps, hold. Legacy --easing remains supported.

MCP server#

Start with an optional default project (connect can change it):

flux mcp /path/to/project

Register supported agents with connect setup (below). Prefer MCP when you want to see a figure (get_figure_image returns the PNG inline) or act on the user’s live selection.

Provenance and locks#

• Every write appends a line to .meta/journal.ndjson (ts, client, action). Read it to see what changed since you last looked ({action, client} per line).
• Writes take advisory locks (project for figures, manuscript for prose/comments/notebook log entries). If you get deferred: "<name>" is locked …, the user is mid-edit in the app — wait a moment and retry. The operation owns renewal/release; do not remove a lock or force a write.

MCP connection and paths#

flux mcp [root] [--toolset core|full] starts the stdio server. It can start without a project. A root argument, FLUX_PROJECT, or the nearest project within eight cwd levels supplies a default root; this alone does not connect or load context. Call connect {target:"/path/to/project"} only when the user asks for flux-connect. Use target:"global" for global context; it preserves any existing project binding. A project tool accepts an optional project override; relative overrides resolve against the bound project and do not change it. With no binding, pass an absolute project path.

CLI filesystem inputs resolve relative to the shell cwd. MCP filesystem inputs resolve relative to the project root. Absolute paths are honoured. Machine/file tools work unbound with absolute paths; relative paths require a project default. Document and folder identifiers remain project-relative model identifiers on both surfaces.

The default core toolset is compact. flux_verbs lists every verb and tool in one line each; flux_verbs {query} returns the matches with their schemas; flux_verb {verb, args} runs any of them with the same validation and result as its dedicated tool, including tools the core list does not show. Select --toolset full or FLUX_MCP_TOOLSET=full to expose all dedicated tools. The MCP connect prompt provides a skill-free entry.

Agent installation and health#

Setup is a user-authorized CLI operation, outside the MCP verb registry:

flux connect setup --dry-run
flux connect setup --agents claude,codex
flux connect doctor --json
flux connect remove --agents codex --yes

Setup preserves unmanaged skills and unrelated registrations, and backs up changes. Use --yes to confirm a replacement, --use-this-install to select the launcher owner, or --create-local-bin for convenience shims. Restart agent sessions afterward. Codex users review the installed refresh hook in /hooks. The read-only core MCP connect_doctor returns the same per-check diagnostics; it cannot change agent config. Personal UserContext skills publish only to connected vendors, with collisions and edited copies left intact. The flux-connect skill itself requires explicit invocation.