CLI

The zudo-composer commands for local authoring, generation, builds, and verification.

Overview

The installed zudo-composer bin is the host's entry point for development, creation, generation, CMS seeding, static builds, release operations, and asset imports. Its public invocation is:

zudo-composer <command> [options]

Commands at a glance

The parser calls the last command assets-import internally; the public shell spelling is assets import. There is no separate zudo-composer assets-import command.

Common behavior

With no command, or with help, --help, or -h, the launcher prints its usage text and exits successfully. A parser error writes [zudo-composer] <reason> followed by the usage text to stderr and exits 1. The launcher resolves command paths to absolute paths before passing them to a child, so relative paths are interpreted from the caller's current directory unless a command says otherwise.

dev runs in the current process because the Vite server owns its listener. init, generate, seed, build-site, release, and assets import run in supervised child processes. A successful one-shot command exits 0; command failures are nonzero and the child status is preserved by the launcher.

dev

Start the authoring server for the host in the current directory:

zudo-composer dev

The server resolves the host config and component pack before it listens. A successful invocation remains running until it receives a terminating signal; startup, config, pack, or listener failures exit nonzero.

init

Create a complete host in one new directory:

zudo-composer init my-site

The two tarball flags must be supplied together. The creator validates their package metadata, installs matching dependencies in a temporary isolated host, runs generation, asset import, and ready-workspace production, then copies the retained tree to the destination. It is create-only: an existing destination is preserved, and the command does not upgrade or migrate it. See Installing into a host for the seeded files and preview workflow.

The parser returns these errors before spawning the creator. Invalid package names, an existing target, a missing parent, archive metadata mismatch, and installation or bootstrap failures are creator errors and exit 1. A successful creation exits 0.

generate

Generate the canonical aggregate from the host-authored site-project.ts:

zudo-composer generate

Normal mode evaluates the default-exported site, validates it against the resolved component pack, and writes site-project.json when it changed. It prints Wrote <absolute-path> or Unchanged <absolute-path>. Check mode prints Current <absolute-path> when the committed aggregate matches. A missing or stale aggregate is an error, so use normal mode to update it.

Parser, config, pack, evaluation, validation, missing-source, and stale-output errors exit 1. A successful write, no-op, or current check exits 0.

seed

The default mode reads site-project.json from the host root, publishes its committed project, and activates the resulting local release:

zudo-composer seed

Plain seed prints one JSON result containing the release identity and a status of activated or unchanged. Ready-workspace mode prints the same identity with workspaceId, a status of created or unchanged, and sorted directory and file inventories (including SHA-256 file digests). Existing different ready-workspace output is preserved and rejected; use a fresh --output directory to review a new generation. The workspace details and regeneration rules are covered by the Site Project and Static Build architecture page.

Parser, config, project validation, release checks, filesystem conflicts, and seed failures exit 1. Successful activation, unchanged output, or ready workspace creation exits 0.

build-site

Build and verify a host's static website:

zudo-composer build-site

Without --verify or --print-routes, the command evaluates the host config and project, builds to <host>/dist-site, writes site-manifest.json, and verifies every emitted file and route. --print-routes is a read-only artifact inspection mode; --verify is also read-only and does not load the host config or compile the project. A normal successful run prints a summary such as Static site verified: <project>, <files> files, <routes> routes, tool <name>@<version>.; a source revision adds , source <revision> before the period. Route and asset surfaces are described in Routes and assets.

--verify and --print-routes are a supported combination, not an error. Parser, build, missing-artifact, manifest, checksum, route, and source-revision verification failures exit 1. A verified artifact or completed build exits 0.

release

Run the local SiteProject release API:

zudo-composer release

The command accepts exactly one UTF-8 JSON request on stdin (up to 8 MiB) and writes exactly one canonical JSON response plus a newline to stdout. The request and operation shapes are documented in the repository's SiteProject operator guide; the Site Project and Static Build architecture page explains the role of the committed project and release identity. The top-level launcher forwards arguments after release unchanged; there are no documented release flags, because the protocol is carried on stdin.

Protocol failures remain JSON responses; they are not replaced by a human-only stderr message. Never infer activation from an apply or build response; inspect the exact response and release identity.

assets import

Import host-owned asset files from a manifest:

zudo-composer assets import images-src/manifest.json

The importer validates the complete manifest and source bytes before writing to the configured assetsDir. Repeating an import skips matching filenames and checksums and reports a canonical response such as { "ok": true, "result": { "added": 1, "skipped": 0 } }. This command is the CLI counterpart to the host's local Assets authoring workflow; published bytes are delivered from publicAssetsDir as described in Routes and assets.

Successful imports exit 0. Manifest validation, missing sources, and known filesystem conflicts return one canonical error response and exit 2. An unexpected internal failure writes an internal error response, reports the underlying detail on stderr, and exits 1.