Command line

Scripts and agents can work on the same project as the app. Flux ships three programmatic surfaces over one shared core:

• The flux CLI — around a hundred typed commands (“verbs”) that operate on a project’s files directly: compose figures, restyle plot parts, manage references, compile the manuscript, build slide decks.
• The MCP server — the same verbs exposed as typed tools for AI agents, plus a few agent-only niceties (inline figure PNGs so an agent can look at its work).
• The live bridge — while the app is open, commands can act on the running GUI: read what you have selected, apply an edit as an undoable action you watch happen.

You never have to use any of this — the app is complete on its own. But it’s what makes the flux-connect workflow possible, and it’s handy for scripting.

Invoking#

On first run Flux creates a stable launcher at ~/.local/share/flux/bin/flux on Linux and macOS. Add that folder to PATH or use the full path; optional ~/.local/bin shims delegate to it. Then:

flux help                 # every verb, always current
flux config               # this machine's resolved paths (FluxConfig, FluxLib, …)
flux list                 # figures + references of the current project

Commands find their project as: an explicit --root, else the FLUX_PROJECT environment variable, else the current directory. cd into a project (or export FLUX_PROJECT) and go.

Connect an agent#

Run flux connect /path/to/project in the agent’s shell, or invoke its installed flux-connect skill. The command returns the reading plan for a pack; the agent reads it, views its images, returns a receipt and waits for your request. global connects without choosing a project; --refresh, --depth full and --live control refresh, reading depth and live pairing. Connect an agent explains setup and the receipt.

Common tasks#

The installed app includes the PNG renderer used by the CLI and MCP. An agent can view figures and canvas overviews without a source checkout or a separate renderer install.

# Compose plots into one labeled multi-panel figure, then render it to look at
flux compose-figure plots/*.svg --id fig1 --rows 2
flux render-figure fig1 --png --out /tmp/fig1.png

# Restyle one part, or a whole series and its legend swatch (both survive regeneration)
flux restyle fig1 control.line --stroke '#205EA6'
flux set-series-color fig1 control '#205EA6'

# Read the plot's data: exact x/y, bins, statistics and brackets
flux get-plot-data fig1 --series control --limit 50

# Add a reference to the project, then compile the manuscript with Quarto
flux cite-doi 10.1038/nature12373
flux compile --to pdf

Edits made headless show up live in the open app, and if you’re mid-edit in the app when a command arrives, it defers politely instead of clobbering (saving and outside edits).

Full command reference#

The CLI and MCP command reference lists the project, figure, plot, document, library, slide and agent commands for the Flux version this site documents.

Use flux help for the list in your installed version, or flux help <verb> for a command’s flags. flux version identifies the installation. The same reference is available locally in FluxConfig/Context/FluxContext/CLI-REFERENCE.md.

For example, flux help read-log prints:

  read-log [--tail <value>] [--since-checkpoint] [--titles] [--json] [--root R]
      Read the project Log: the latest entries, from the latest checkpoint, or titles only.

Connecting an MCP client#

Point an MCP client at the launcher with args = ["mcp"]; add a project path after mcp for a fixed default. The optional ~/.local/bin/flux and flux-connect shims delegate to the same launcher. On Windows the launcher is %LOCALAPPDATA%\flux\bin\flux.cmd, although Windows does not yet have a supported installer.

flux mcp starts with the compact core toolset. Use flux_verbs to discover commands and flux_verb to run them, or flux mcp --toolset full for every dedicated tool. Ask the agent for flux-connect /path/to/project to bind it. Finding a project from cwd only supplies a default for tools; it does not load context. Project tools can also take a project argument for one call.

Relative filesystem inputs use the shell cwd on the CLI and the project root over MCP. Absolute paths are honoured. Document identifiers remain project-relative.

Agent setup and diagnostics#

flux connect setup --dry-run previews installation. Apply with flux connect setup; --agents claude,codex selects vendors, --yes confirms replacing an existing Flux registration, and --create-local-bin creates the optional convenience shims. Flux prints the macOS PATH instruction; it never edits shell startup files.

flux connect doctor checks the launcher, full MCP handshake, PNG rendering, context files, published skills, hooks, registrations and known projects. --json returns the same checks as the read-only MCP tool connect_doctor. Setup and removal are CLI actions and cannot be invoked over MCP.

On Windows, setup registers the pinned runtime and CLI script directly; MCP hosts do not have to execute a .cmd shim. Run setup again after relocating Flux.

Troubleshooting#

Use flux connect doctor for launcher, tools and integration errors. After moving an installation, rerun setup and restart agent sessions. A missing flux command usually means the launcher directory is not on PATH; use its full path above.