CLI Reference

FluidCAD ships a command-line tool alongside the library. It scaffolds a project, runs the server that backs the 3D viewport, writes STEP/STL/PNG files without opening the UI, and exposes the MCP server that lets AI agents drive your workspace.

FluidCAD is installed per-project, so the CLI is run through npx from inside the project:

npm i fluidcad
npx fluidcad --help

note

A global install (npm install -g fluidcad) is not supported — the engine and your editor's type hints both resolve from the project's node_modules. If you see Cannot find module 'fluidcad' imported from …, run npm i fluidcad inside the project.

Command	What it does
`fluidcad init`	Scaffold a new project in the current directory
`fluidcad serve`	Start the server and watch `.fluid.js` files
`fluidcad export step`	Write a STEP file
`fluidcad export stl`	Write an STL mesh
`fluidcad export png`	Capture a PNG of the viewport
`fluidcad mcp`	Run the MCP server over stdio

Every command accepts --help, and npx fluidcad --version prints the installed version.

`fluidcad init`

npx fluidcad init

Scaffolds a project in the current directory:

my-app/
├── init.js             ← required project entry point
├── test.fluid.js       ← starter model
└── jsconfig.json       ← enables editor type hints

init.js is required — the viewer cannot run a .fluid.js file without it. Don't edit it.

The command refuses to run if init.js already exists, so it can't clobber a project. test.fluid.js and jsconfig.json are only written when they're missing, so re-running it in a half-set-up folder fills in the gaps.

This command takes no options.

`fluidcad serve`

npx fluidcad serve

Starts a local FluidCAD server, renders the first .fluid.js file it finds, and watches the workspace — the viewport refreshes every time you save. Open the printed URL (http://localhost:3100 by default) in a browser to see the model. Press Ctrl+C to stop.

This is the "any editor" path: use it when you're not running the VS Code or Neovim extension.

Flag	Description	Default
`-w, --workspace <path>`	Path to your project	Current directory
`-p, --port <port>`	Server port — if it's taken, the first free port above it is used	`3100`
`--open`	Open the viewport in your default browser once the server is ready	off

npx fluidcad serve --open              # start and launch a browser
npx fluidcad serve -w ./my-app         # serve a project in another directory
npx fluidcad serve -p 4000             # start at port 4000 (4001, 4002, … if busy)

note

Interactive features — region picking, trimming, interactive bezier drawing — need the VS Code or Neovim extension. serve gives you a view-only viewport that refreshes on save.

`fluidcad export`

npx fluidcad export step                          # every shape → <entry>.step
npx fluidcad export stl --resolution fine -o parts/bracket.stl
npx fluidcad export png --view front --open

Writes a STEP, STL, or PNG file straight from the terminal — the same exports the Export dialog produces, without opening the UI.

How the model gets rendered

The CLI works in one of two modes, chosen automatically:

Attached — a FluidCAD server is already running for the workspace (started by fluidcad serve or an editor extension). The CLI finds it through .fluidcad/instance.json and exports the scene that server is currently showing. Nothing is re-rendered, and no second server is started.
Ephemeral — nothing is running. The CLI forks its own server on a free port, renders your entry file, exports, and shuts the server down again.

Because an attached server's scene wins, passing --entry while one is running only prints a warning — what the server shows is what gets exported. Stop the server to export a different file.

Common flags

These apply to all three formats:

Flag	Description	Default
`-w, --workspace <path>`	Path to your project	Current directory
`-e, --entry <file>`	Which `.fluid.js` to render	The workspace's only one
`-o, --out <path>`	Output file	`<entry>.<ext>` in the current directory
`-p, --port <port>`	Export from the running server on this port instead of discovering one	Auto-discovered
`--timeout <sec>`	Seconds to wait for the server (and, for `png`, for a browser)	`60`

If the workspace holds more than one .fluid.js file, --entry is required — the CLI won't guess.

`fluidcad export step`

Flag	Description	Default
`--shapes <ids...>`	Export a subset of the scene's shapes	All shapes
`--list-shapes`	Print the scene's shapes and exit without exporting	—
`--no-colors`	Write plain geometry instead of per-shape colors	colors on

npx fluidcad export step --no-colors -o build/housing.step

`fluidcad export stl`

Flag	Description	Default
`--shapes <ids...>`	Export a subset of the scene's shapes	All shapes
`--list-shapes`	Print the scene's shapes and exit without exporting	—
`--resolution <r>`	Mesh resolution: `coarse`, `medium`, `fine`, or `custom`	`medium`
`--linear-deflection <mm>`	Custom linear deflection, in mm	—
`--angular-deflection <deg>`	Custom angular deflection, in degrees	—

The two deflection flags imply --resolution custom, and custom needs both of them:

npx fluidcad export stl --linear-deflection 0.01 --angular-deflection 0.1

Passing a deflection alongside --resolution fine is an error rather than a silent override.

Picking shapes

--list-shapes prints what the scene contains, numbered:

shapes:
a1f2…  SOLID  Extrude
b7c4…  SOLID  Fillet
c9e0…  SOLID  Housing

--shapes then takes any mix of:

a position from that listing — --shapes 1 2
a feature name — --shapes Housing (case-insensitive; exports every shape that feature produced)
a shape id — --shapes a1f2…

Positions and names survive a re-render; shape ids are minted fresh every time the model rebuilds, so don't hard-code them in a script.

npx fluidcad export step --list-shapes
npx fluidcad export step --shapes 1,3 -o build/plates.step
npx fluidcad export stl --shapes Housing --resolution fine

`fluidcad export png`

Flag	Description	Default
`--width <px>`	Image width	`800`
`--height <px>`	Image height	`800`
`--view <name>`	Camera view (see below)	`iso-ftr`
`--margin <px>`	Crop/fit margin	`20`
`--transparent`	Transparent background	off
`--show-axes`	Show the origin axes	off
`--no-grid`	Hide the ground grid	grid shown
`--no-auto-crop`	Keep the full frame instead of cropping to the model	crop on
`--no-fit`	Don't fit the camera to the model	fit on
`--open`	Open the viewport in a browser to render the capture	off

--view takes current (whatever the connected browser is looking at) or a named view:


Orthographic	`front`, `back`, `left`, `right`, `top`, `bottom`
Isometric	`iso-ftr`, `iso-fbr`, `iso-ftl`, `iso-fbl`, `iso-btr`, `iso-bbr`, `iso-btl`, `iso-bbl`

Isometric names read as front/back, top/bottom, left/right — iso-fbl is the front-bottom-left corner.

npx fluidcad export png --view top --width 1600 --height 1200
npx fluidcad export png --transparent --no-grid -o docs/hero.png

warning

PNG capture needs a browser. Screenshots are rendered by the FluidCAD viewport itself, so a browser has to be connected to the server. Pass --open and the CLI launches one and waits for it; otherwise open the server URL yourself before the --timeout runs out.

If a server is already attached and no browser is on it, the command fails immediately and tells you the URL to open — re-run with --open, or stop that server so the CLI can spawn its own.

`fluidcad mcp`

npx fluidcad mcp

Runs the FluidCAD MCP server over stdio, so an LLM agent can drive your workspace: take screenshots, inspect geometry, measure, edit source, and look up the API. It's bundled with the fluidcad package — there's nothing extra to install.

You don't normally run this by hand; you register it with an MCP client.

Claude Code — register at user scope so it's available in every project:

claude mcp add --scope user FluidCAD -- npx -y fluidcad mcp

Claude Desktop / Cursor — add to claude_desktop_config.json or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "FluidCAD": {
      "command": "npx",
      "args": ["-y", "fluidcad", "mcp"]
    }
  }
}

opencode — run opencode mcp add, or add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "FluidCAD": {
      "type": "local",
      "command": ["npx", "-y", "fluidcad", "mcp"],
      "enabled": true
    }
  }
}

Then install the companion skill so agents follow the FluidCAD workflow:

npx skills add Fluid-CAD/FluidCAD

The agent drives a running workspace, so start one first — with fluidcad serve or an editor extension — and the MCP server attaches to it.

See the MCP README for the full tool surface and transport details.

fluidcad init​

fluidcad serve​

fluidcad export​

How the model gets rendered​

Common flags​

fluidcad export step​

fluidcad export stl​

Picking shapes​

fluidcad export png​

fluidcad mcp​