Build Command

build is the main cr4te command. It reconciles metadata and renders the static site.

cr4te build -i path/to/Creators -o path/to/site

Common Examples

cr4te build -i path/to/Musicians -o path/to/site --domain music
cr4te build -i path/to/Artists -o path/to/site --domain art
cr4te build -i path/to/Creators -o path/to/site --strict
cr4te build -i path/to/Creators -o path/to/site --clear-thumbnail-cache --force
cr4te build -i path/to/Creators -o path/to/site --open

Required Options

• -i, --input: path to the library root containing creator folders.
• -o, --output: path to the generated site folder.

The input and output paths must be different. The output path cannot be inside the input path, and the input path cannot be inside the output path.

Config Options

• --config: load a JSON config file.
• --domain: apply a domain preset.
• --image-sample-strategy: use none to select no gallery images, spread to distribute selections, head to select the first images, or all to select every image.
• --portrait-discovery: use named for configured basename matches only or auto to also permit portrait-oriented fallback images.
• --portrait-visibility: use disabled to hide portraits, details for detail pages only, or all to also show portraits on overview cards.

Custom Themes

• --themes-dir: include custom theme CSS files from the selected folder.

Relative paths resolve from the current working directory. The folder must exist and be a directory; otherwise the build aborts before changing metadata or output files.

See Custom Themes for theme file rules and examples.

Build Behavior Options

• --strict: fail immediately on invalid metadata instead of skipping/reporting invalid entries.
• --open: open index.html after a successful build.
• --force: skip confirmation before replacing an existing output folder.
• --clear-thumbnail-cache: remove cached thumbnails before building.

Exit Status

The command uses intentional process exit statuses:

• 0: successful build, completed best-effort build, or explicit user cancellation.
• 1: strict-mode, structured build, or expected operational build-phase failure.
• 2: invalid command arguments, configuration, or paths.

Existing Output Folder

If the output folder already exists, cr4te asks before clearing it.

By default, it preserves the thumbnails folder so rebuilds can reuse generated thumbnails. Use --clear-thumbnail-cache to remove cached thumbnails before rebuilding.

Use --force when running non-interactively:

cr4te build -i path/to/Creators -o path/to/site --force

Build Summary

At the end of a build, cr4te logs a summary:

Build summary: creators=15, projects=17, errors=0, warnings=0
Build timings: themes=0.001s, output=0.017s, metadata=0.002s, indexing=0.011s, rendering=0.295s, total=0.326s
Asset links: symbolic=0, hard=18, reused=0
Source thumbnails: generated=0, reused=31, default_uses=0, hash_checks=0

The timing line shows how long each successful build phase took:

• themes: discover and validate built-in and custom themes.
• output: clear or create the output folder.
• metadata: create and reconcile editable metadata files.
• indexing: scan and validate the media library.
• rendering: generate pages, stage media, and prepare thumbnails.
• total: sum of the reported phases.

Asset statistics count operations performed while rendering:

• symbolic: new symbolic media links created.
• hard: new hard media links created after symbolic-link creation was unavailable.
• reused under asset links: existing staged media links reused during the build.
• generated: source-derived thumbnails created or regenerated.
• reused under source thumbnails: existing source-derived thumbnails reused.
• default_uses: generated default thumbnails used because no source image was configured or a source thumbnail was unavailable.
• hash_checks: source images hashed to compare their content with existing thumbnail hash sidecars.

These counters help distinguish a cold build from a warm-cache build and identify which phase dominates build time. They use constant memory and do not add per-file progress logging.

If best-effort mode encountered issues, they are listed with severity, scope, relative path, issue code, and message.

Metadata reconciliation skips and render-time asset problems also appear in this summary. Reconciliation and indexing reports for the same scope, issue code, and path appear only once. Recoverable asset failures do not leave known-broken references in the generated site:

• Missing media and unreadable text or gallery images are omitted.
• Failed portrait and cover thumbnails use generated defaults.
• Unavailable optional inspection data, such as audio duration, uses a safe fallback and produces a warning.

Repeated failures with the same asset path and issue code are reported once per build.

Expected operational failures identify the failed phase, such as output preparation or HTML rendering. Unexpected programming errors are not converted into recoverable build issues.

Best-Effort vs Strict

Default behavior is best-effort:

• Invalid creator metadata skips that creator.
• Invalid project metadata skips only that project.
• Recoverable asset failures use safe fallbacks or omit the affected media item.
• Warnings, such as unknown collaboration references, are reported.

Strict behavior:

cr4te build -i path/to/Creators -o path/to/site --strict

With --strict, metadata and asset errors fail immediately. Asset warnings continue.

Other Commands

Print the resolved config:

cr4te print-config
cr4te print-config --domain music

Delete metadata files:

cr4te delete-metadata -i path/to/Creators --dry-run
cr4te delete-metadata -i path/to/Creators --force

Use --dry-run to list creator and project cr4te.json files without deleting them. Use --force to skip the deletion confirmation. Media files are not affected.