GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
cli.mdRendered Markdown

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.

Document metadata

convert, run --out and batch keep the document's XMP packet in a flat export whose format holds one (PNG, JPEG, WebP, TIFF, …), and its free-form text where the format holds that too (PNG text chunks, TIFF's named text tags such as ImageDescription; JPEG and WebP have no place for it), as Save As does. --metadata none leaves them out, as Export As's Metadata: None does: a Photoshop file's XMP can list every placed document's id (DocumentAncestors) and the text of every type layer, and can be far larger than the image. --metadata all is the default. The option changes nothing else: the ICC profile, EXIF and resolution are written as they are without it, where the format holds them. An Indexed Color document saved as a palette PNG carries no XMP, text, ICC profile or EXIF with either value, only its resolution. PSD, PSB and .pcraft saves always keep the XMP. It is not a full metadata scrub.

photocraft-cli batch --actions resize.json --in masters/ --out web/ \
  --format webp --metadata none

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 checks the flags and their values before any work starts. A flag the subcommand doesn't take (a typo such as --fromat), a flag given twice (only --cmd and --params may repeat), a value out of range (--quality 0), malformed --new or --params JSON, <FILE> together with --new, and --control-token together with --control-token-file are all usage errors (exit status 2), rather than being ignored or failing later. A value flag never takes the next flag as its value, so a value starting with - is written with = (--out=-image.png) or as ./-image.png; negative numbers such as --filter -1 still work. A path that is not valid Unicode reaches the command instead of being a usage error: convert reads and writes it, while info, run and batch open files through the automation layer, which still needs UTF-8 paths and fails with exit status 1 (droplet takes its arguments as text, so it refuses such a path as a usage error). photocraft-cli --version (or -V) prints the version; there is no version subcommand.

mcp and serve reject positional arguments, empty values and options for the wrong mode before starting a server. Explicit control-token flags require mcp --bridge or serve --port (or PHOTOCRAFT_CONTROL_PORT, below). Configure automation roots on the desktop process when using bridge mode; the CLI rejects root flags there. See the MCP launch guide for examples.

mcp and serve fall back to environment variables: PHOTOCRAFT_CONTROL_TOKEN and PHOTOCRAFT_CONTROL_TOKEN_FILE for the token flags, and PHOTOCRAFT_CONTROL_PORT for serve --port and mcp --bridge (which then bridges to 127.0.0.1:<port>). The automation roots are flags only: the desktop app's PHOTOCRAFT_AUTOMATION_READ_ROOT and PHOTOCRAFT_AUTOMATION_WRITE_ROOT grant the CLI nothing. A flag wins over its variable, an empty variable counts as unset, and a bad value is a usage error naming the variable. When PHOTOCRAFT_CONTROL_PORT switches serve to TCP or mcp to bridging, the command says so on standard error. A token together with a token file is a usage error only where a token is read (serve on TCP, mcp bridging), so a stale exported pair doesn't stop stdio serve or headless mcp. An automation root given to mcp while the variable would switch it to bridging is a usage error too: the roots are the headless engine's, and the bridge would drop them. <subcommand> --help lists each variable (unless it is set but empty), never with the token's value. A variable holds a port, so PHOTOCRAFT_CONTROL_PORT=127.0.0.1:7878 is refused; only --bridge takes host:port.

This checking is not a security policy layer. Engine commands remain responsible for validating their own parameters.

Shell completions and man pages

The Linux .deb and .rpm packages install man photocraft-cli (plus a page per subcommand, such as man photocraft-cli-convert) and completions for bash, zsh and fish (zsh's in /usr/share/zsh/site-functions, which the .deb also links from Debian's /usr/share/zsh/vendor-completions); the Linux tarball and the FreeBSD tarball carry the same files, the FreeBSD one under man/man1 and share/. The pages list each flag's environment variable, as --help does. Without a package, generate them from a source checkout:

cargo run -p photocraft-cli --example man-and-completions -- out/

out/ then holds photocraft-cli.bash, _photocraft-cli (zsh), photocraft-cli.fish, photocraft-cli.elv (elvish), _photocraft-cli.ps1 (PowerShell) and the .1 man pages. For example, copy photocraft-cli.bash to ~/.local/share/bash-completion/completions/photocraft-cli, photocraft-cli.fish into ~/.config/fish/completions/, _photocraft-cli into a directory on zsh's $fpath, and read a page with man -l out/photocraft-cli.1. The desktop app photocraft has neither.