docs / Command-line reference (brep-app)

Command-line reference (brep-app)

Everything the brep-app executable accepts on its command line, what each switch takes, its default and what it does. brep-app --help prints the same list in short.

Started with no arguments, brep-app opens the CAD window. A few switches open a different window (the KiCad importer), and the rest are terminal commands: they do their work, print what they did and exit without opening any window, so an installer or a script can run them unattended.

On Windows the executable is a windowed program, so a Start-menu launch opens no console. Run from a terminal with any argument, it attaches to that terminal, so --version, --plm-show, --plm-check and the other commands print there and their exit codes reach the caller.

brep-app [FILE] [--mcp [--mcp-port PORT] [--session-root DIR]] [--plm-url URL] [--plm-token-file FILE]
brep-app --kicad-library
brep-app --install-file-associations | --uninstall-file-associations
brep-app --plm-configure URL [--plm-token-file FILE] | --plm-forget | --plm-show | --plm-check
brep-app --bake-worker [--plm-url URL] [--plm-token-file FILE] [--once | --poll SECS]
brep-app --version
brep-app -h | --help

Opening the CAD window

Switch	Argument	Default	Effect
`FILE`	a path	none	Open this document in a tab at startup: a part (`.nbrep`), a family seed (`.fbrep`) or a template (`.tbrep`). This is what a file association passes on a double click. Only one document can be named; a second path is an error.
`--mcp`	none	off	Embed the MCP server, so an AI agent drives this window over `http://127.0.0.1:PORT/mcp`. Every request needs the bearer token in `mcp-token` in the app's config directory (minted on first start, readable by you only). The terminal prints how to connect Claude Code or Codex with it. See Driving BREP from an AI agent. A build made without MCP support exits with an error.
`--mcp-port`	`PORT`	`8765`	The port the MCP server listens on. Needs `--mcp`. A port already in use stops the launch with an error rather than opening a window without its server.
`--session-root`	`DIR`	`BREP_MCP_SESSION_ROOT`, else a `brep-mcp` folder in the system temporary directory	Where MCP sessions keep their screenshots and call logs. Needs `--mcp`.
`--plm-url`	`URL`	`BREP_PLM_URL`, else `plm.json` in the config directory	Connect this session to the PLM server at `URL`. See Connecting the CAD app.
`--plm-token-file`	`FILE`	`BREP_PLM_TOKEN`, else `plm-token` in the config directory	Read this session's PLM API token from `FILE`. The token itself is never a command-line argument, because any user of the machine can read a running program's command line.

With no PLM configured anywhere, the app is the file-based app. A PLM that is configured but cannot be used as written (a malformed URL, a token file that is not a token) is reported in the terminal and in the window, and the session starts on the local file stores: a PLM problem never stops the app from starting.

The KiCad importer

Switch	Argument	Default	Effect
`--kicad-library`	none	off	Open the KiCad importer instead of the CAD window: clone KiCad's symbol, footprint and 3D-model libraries with git (about 5.6 GB, once, into `kicad-library/<release>/` in the app's config folder: `%APPDATA%\brep-app` on Windows, `~/.config/brep-app` elsewhere), or import parts from KiCad folders on this machine, saving each part as a document. `git` must be on the PATH for the clone; without it, or without network access, the importer says why and asks for the folders instead. It has no 3D view and no workbench.

File associations

Switch	Argument	Effect
`--install-file-associations`	none	Make this executable the program that opens `.nbrep`, `.fbrep` and `.tbrep` files for the current user, and print every record it wrote. On Linux the records go under `XDG_DATA_HOME` (else `~/.local/share`).
`--uninstall-file-associations`	none	Remove that association again.

Both exit 0 when every record was written or removed and 1 when one could not be; a missing desktop refresh tool is only a warning.

PLM configuration commands

These read or write the two PLM files in the app's config directory (see Files and environment) and exit. They print to standard output and exit 0 on success; a failure prints one sentence to standard error and exits 1.

Switch	Argument	Effect
`--plm-configure`	`URL`	Write `plm.json` naming the server, and, with `--plm-token-file`, copy the token into `plm-token` (readable only by you on Linux and macOS). Without a token file an existing `plm-token` is left alone, so re-pointing a machine at a moved server keeps its sign-in. Prints what the next launch will use.
`--plm-forget`	none	Remove `plm.json` and `plm-token`. The next launch is the file-based app.
`--plm-show`	none	Print the server this launch would use and where each part of the setting came from (command line, environment or config file). The token is never printed, only its first characters.
`--plm-check`	none	Sign in to that server and check that it accepts this version of the app, exactly as a window launch would. Exits 0 when it connects and 1 with the server's refusal when it does not.

--plm-show and --plm-check honour --plm-url and --plm-token-file, so you can test a server before configuring it.

The bake worker

--bake-worker runs the app with no window as the PLM's headless worker: it takes each queued family member, template copy or resave job from the PLM, builds it, writes the result back or reports why it failed, and prints one line per job. See Families, templates and the bake worker.

It must be the first argument, and it takes only these switches after it:

Switch	Argument	Default	Effect
`--bake-worker`	none	—	Run as the bake worker.
`--plm-url`	`URL`	`BREP_PLM_URL`, else `plm.json`	The PLM server.
`--plm-token-file`	`FILE`	`BREP_PLM_TOKEN`, else `plm-token`	A file holding the API token. A token of `worker` scope is enough.
`--once`	none	off	One pass over the queue, then exit.
`--poll`	`SECS`	`30`	Seconds to wait between passes while the queue is empty.

--once and --poll do not go together. Exit codes: 2 for a bad switch, a missing server or a missing token; 3 when the server does not answer, refuses the token, or stops accepting it mid-run (it was revoked); 0 after a --once pass. A job that fails is reported on its line and does not stop the worker.

Information

Switch	Effect
`--version`	Print `brep-app <version>` and exit. Installers compare this with the PLM server's oldest accepted version.
`-h`, `--help`	Print the usage text and exit.

Switches that do not combine

The app refuses a combination that cannot mean anything, rather than silently ignoring part of it. A refusal prints the reason and the usage text and exits 2.

--mcp-port and --session-root need --mcp.
--install-file-associations and --uninstall-file-associations open no window, so they take no FILE, --mcp or --kicad-library.
--kicad-library opens the importer, so it takes no FILE and no --mcp.
--plm-configure, --plm-forget, --plm-show and --plm-check open no window, so they take no FILE, --mcp, --kicad-library or association switch, and only one of them can be given.
--plm-configure takes the URL itself, so it refuses --plm-url.
--plm-forget takes neither --plm-url nor --plm-token-file.
Any other argument beginning with - is an unknown switch, not a file name.

Files and environment

The config directory holds the app's settings, its local model store and the two PLM files. It is the first of these that is set and not empty:

$XDG_CONFIG_HOME/brep-app
on Windows, %APPDATA%\brep-app
$HOME/.config/brep-app
./brep-app

The PLM files in it:

plm.json: {"url": "https://plm.example.com"}, the server. Not a secret.
plm-token: the API token (plm_…) alone. A secret, written readable only by you.

Which server and token a launch uses: a command-line switch wins over an environment variable, which wins over the config file. An empty variable counts as unset, so BREP_PLM_URL= brep-app starts the file-based app even on a configured machine.

Variable	Effect
`BREP_PLM_URL`	The PLM server, unless `--plm-url` is given.
`BREP_PLM_TOKEN`	The PLM API token, unless `--plm-token-file` is given.
`BREP_MCP_SESSION_ROOT`	Where MCP sessions keep screenshots and call logs, unless `--session-root` is given.
`BREP_MCP_TOKEN_FILE`	The MCP server's token file, in place of `mcp-token` in the app's config directory.
`RUST_LOG`	Diagnostic output on standard error, for example `RUST_LOG=info` or `RUST_LOG=brep_app=debug`. Errors only by default.