cadcraft-cli is headless CADCraft: it reads, converts and exports drawings, runs scripts and
commands, prints the command catalog and serves MCP. It follows
RFC-0012: Command-line conventions.
cadcraft-cli --help and cadcraft-cli help <subcommand> (or <subcommand> --help) are the
reference for every subcommand, flag and value; this page doesn't repeat them. Examples are in the
README, MCP setup in mcp.md,
scripts and the JSON command forms in customization.md.
| Exit codes | 0 success, 1 the command failed, 2 usage error. |
| Streams | Results on stdout. info and commands print pretty JSON, or one line with --compact; run prints one JSON line per --cmd result (JSON lines); a command with no result (JSON null) prints no line. Errors (error: …), warnings and wrote … lines on stderr. mcp speaks MCP on stdout and writes nothing else there. |
| Usage errors | An unknown or repeated flag, a missing or malformed value (--window, --view, --cmd JSON, a sample name), flags that conflict (--window with --view) or that need another (run --window without --export) stop before any work, with exit 2. --script, --script-file, --cmd and run's files repeat and run in command-line order. |
| Outputs that replace an input | convert IN OUT and run FILE… --save OUT / --export OUT refuse an OUT that is the same file as an input (any spelling or symlink of it): usage error, exit 2, nothing opened or written. --in-place allows it. A save a script or --cmd runs is the engine's. |
Values starting with - |
Written with =: --window=-10,-10,10,10, --export=-plan.png. |
| Paths | Read as given, including names that aren't valid Unicode. The engine opens files by text name, so such a name is reported as an error (exit 1) where a drawing is opened; an output takes any name whose extension is ASCII. |
| Completions and man pages | The Linux packages install them. To generate them yourself: cargo run -p cadcraft-cli --example man-and-completions -- <out-dir>. |
Variables are fallbacks for flags; --help shows each next to its flag. An empty value counts as
unset and the flag wins over the variable, except for CADCRAFT_CONFIG_DIR (see below).
| Variable | Flag | Subcommands |
|---|---|---|
CADCRAFT_CONFIG_DIR |
--config-dir (the settings folder; plotter configurations are in its plotters folder; empty means no settings folder) |
convert, run, mcp, sample |
CADCRAFT_FONTALT |
--fontalt (FONTALT) |
convert, run, mcp, sample |
CADCRAFT_FONTFALLBACK |
--fontfallback (FONTFALLBACK) |
convert, run, mcp, sample |
The desktop app's are listed by cadcraft --help; its one flag fallback is
CADCRAFT_CONTROL_PORT for --control, where a bad value is a usage error that names the
variable.
CADCRAFT_CONFIG_DIRis the one flag fallback where an empty variable doesn't count as unset (RFC-0012 rule 1.7): empty (or--config-dir "") means no settings folder, as it did before the port.- No variable for
mcp --connect. Photocraft'smcp --bridgefalls back to its*_CONTROL_PORTvariable. Here an exportedCADCRAFT_CONTROL_PORTwould silently switchmcpfrom a headless session to the running app, so--connectstays a flag only. - The desktop app on Windows is built without a console, so a usage error in its launch flags isn't visible there; the app exits with code 2.
- The
string-errorast-grep rule covers the CLI code only. The engine's file hooks (cadcraft_engine::cmd::file::IoHooks) still returnResult<_, String>, soinstall_iomaps errors to strings at that boundary. - No AGENTS.md line for the ast-grep scan. RFC-0012 asks an app's AGENTS.md to have coding
agents run the scan before pushing (
ast-grep scan -c lint/ast-grep/sgconfig.yml); CI runs it on every PR that touches the CLI code. perfprints a text table, with no--json(whether text listings get one is an open question in RFC-0012).- Saves a command or script runs (
--cmd 'saveas {…}', a script'sSAVEAS) are the engine's and are not checked against the opened drawings; only--saveand--exportare.