mirror of
https://github.com/storytold/cadcraft.git
synced 2026-11-21 01:50:50 +01:00
67 lines
5.0 KiB
Markdown
67 lines
5.0 KiB
Markdown
# cadcraft-cli
|
|
|
|
`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](https://github.com/storytold/craft-contrib/pull/18).
|
|
|
|
`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](../README.md#drive-it-from-agents-mcp-and-the-cli), MCP setup in [mcp.md](mcp.md),
|
|
scripts and the JSON command forms in [customization.md](customization.md).
|
|
|
|
## Conventions
|
|
|
|
| | |
|
|
|---|---|
|
|
| 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>`. |
|
|
|
|
## Environment variables
|
|
|
|
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.
|
|
|
|
One variable is not a flag fallback: **`CADCRAFT_CAP_HEIGHT`** pins the cap height a
|
|
metric-compatible substitute font is scaled by, so text on a substitute keeps the size of the
|
|
font it stands in for (`LiberationSans=715.8;LiberationSans-Bold=715.8`; each entry names the
|
|
substitute's PostScript name and the cap height to give it, in font units at 1000 units per em —
|
|
the cap height of the font it replaces, not the substitute's own; entries without a name or with
|
|
a height below 1 or not finite are dropped). It is a packaging hook for installations whose
|
|
substitutes lack the original's OS/2 cap height, and applies to every subcommand.
|
|
|
|
## Not followed yet
|
|
|
|
- **`CADCRAFT_CONFIG_DIR` is 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's `mcp --bridge` falls back to its
|
|
`*_CONTROL_PORT` variable. Here an exported `CADCRAFT_CONTROL_PORT` would silently switch `mcp`
|
|
from a headless session to the running app, so `--connect` stays 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-error` ast-grep rule** covers the CLI code only. The engine's file hooks
|
|
(`cadcraft_engine::cmd::file::IoHooks`) still return `Result<_, String>`, so `install_io` maps
|
|
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.
|
|
- **`perf` prints 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's `SAVEAS`) are the engine's
|
|
and are not checked against the opened drawings; only `--save` and `--export` are.
|