PhotoCraft: An open-source, photo editor written by scratch in pure Rust
Command-line interface
apps/photocraft-cli provides the following current subcommands:
| Command | Purpose |
|---|---|
convert |
Open one document and export it to another format |
info |
Print document size, mode, depth, and layer information as JSON |
run |
Open or create a document, execute engine commands, and optionally save |
batch |
Apply an action list to files in one input directory |
droplet |
Run a PhotoCraft droplet against files or folders |
commands |
List command IDs and parameter documentation |
mcp |
Start the MCP server on stdio, optionally bridged to the desktop app |
serve |
Start the JSON-lines headless server on stdio or loopback TCP |
Use photocraft-cli --help (or photocraft-cli <subcommand> --help) as the executable source of truth. A typical bounded command run is:
photocraft-cli run input.psd \
--cmd image.adjustments.invert \
--out output.png
Missing font warnings
If a type layer uses a font family that is not installed, convert and run
write a warning to standard error before exporting; they do not silently present
the fallback rendering as an exact match. info --compact includes the same
warning in its warnings JSON array, without writing it to stderr. run
also adds warnings to the JSON result for the command that first exposes
the missing family. A multi-command run reports each missing family once,
even if later commands still use it.
Warnings do not change the saved document's font declarations and do not stop
the operation. To list or replace the missing families intentionally, use
type.resolveMissingFonts on the document.
Export selected adjustment layers as a .cube LUT
The engine command file.export.colorLookupTables creates a 3D LUT from an
identity RGB lattice. It can export all visible top-level adjustment layers
(the default), the current Layers panel selection, or a supplied list of
adjustment layer IDs. The scope and layers parameters are mutually
exclusive when scope is selected:
{"size": 33, "scope": "selected", "path": "chosen-look.cube"}
For automation that does not use the Layers panel, supply "layers": [10, 14]
instead. Input ID order does not change the final color look: adjustments are
always baked in document stacking order, bottom to top. When path is
omitted, the command returns the .cube text in cube; both forms return
size and layerCount.
Valid LUT dimensions are 2–129 (same maximum as PhotoCraft's LUT reader). Selected IDs must exist, be visible top-level adjustment layers, and contain no duplicates; invalid selections report an error rather than silently exporting a different look. Masks, vector masks and clipping are spatial operations and cannot be represented faithfully by a color-only LUT, so the baker omits them. Group-contained adjustments are not exported as independent layers because that would lose their group's blending semantics.
Paths supplied to the current CLI are ordinary operating-system paths. The CLI does not restrict them to a workspace root. Batch output creates the requested output directory, and save operations may create parent directories. batch refuses an output directory that is its input directory (the results would replace the originals) unless --in-place is given. Run untrusted action files only in an appropriately isolated account or environment.
CLI parsing reports malformed flags and JSON as errors, and a flag the subcommand doesn't take (a typo such as --fromat) is a usage error (exit status 2) rather than being ignored. It is not a security policy layer. Engine commands remain responsible for validating their own parameters.
mcp and serve reject positional arguments, repeated options, missing or empty values and
options for the wrong mode before starting a server. Explicit control-token flags require
mcp --bridge or serve --port. Configure automation roots on the desktop process when using
bridge mode; the CLI rejects root flags there. See the MCP launch guide for examples.