Skip to content

Project format CLI

Source CLI 0.6.0 · Authored schema: 110 · Updated 2026-10-07. Requires Node 22 or newer. Build it from the repository with npm --prefix tools/project-format ci and npm --prefix tools/project-format run build. Run node tools/project-format/dist/cli.mjs followed by a command. All processing is local; no account or validation service is needed.

The published CLI 0.3.0 supports schema 105; schema-110 standalone publication is pending.

Download a .zq with Download on its Portal project page. The public library integration reference explains programmatic downloads and permissions. Older sources keep their original schema.

Terminal window
node tools/project-format/dist/cli.mjs upgrade downloaded.zq --out current.zq --json
node tools/project-format/dist/cli.mjs extract current.zq --out workspace --fork
# Edit workspace/project.json. Optionally add assets:
node tools/project-format/dist/cli.mjs asset add workspace poster.webp --key assets/poster.webp --name Poster
node tools/project-format/dist/cli.mjs pack workspace --out result.zq
node tools/project-format/dist/cli.mjs validate result.zq --json

Open result.zq in Studio with File → Open File… and review its image, motion, and sound. Omit --fork when updating the original project. Current schema-110 examples can go directly to extract.

CommandFlagsBehavior and successful output
--versionNonePrints CLI version, authored schema, and upgrade range.
--help, -h, or helpNonePrints usage. No arguments also prints help.
upgrade <input.zq>Required --out <new-output.zq>; optional --jsonMigrates 101–109 through Studio’s migration path; 110 is a validated repack. Prints source/target versions, absolute output path, and any migration warnings.
extract <input.zq>Required --out <directory>; optional --forkRequires 110 and a new or empty directory. Writes JSON, assets, and optional preview. Silent on success. --fork gives the outer project a new identity.
asset add <directory> <source-file>Optional --key <relative-path> and --name <label>Copies supported media, creates a descriptor, and prints project-asset:<id>. Default key: lowercase-normalized assets/<filename>; default name: filename. Existing keys/files fail. Quote names containing spaces.
pack <directory>Required --out <output.zq>Requires 110. Refreshes hashes/sizes, including nested modules, validates, writes the bundle, and updates workspace JSON. Prints output path. Existing output is replaced.
validate <directory-or-file.zq>Optional --jsonRequires 110. Checks Studio load, the shared structural contract, graphs, references, simulation source, archive, manifests, blobs, and preview. Does not modify input. Prints success or JSON diagnostics.

asset add supports PNG, JPEG, WebP, GIF, HDR, EXR, MP3, WAV, OGG, FLAC, MP4, WebM, MOV, GLB, GLTF, IES, and ZQSEQ extensions. It creates a descriptor, not a decoder or graph connection. GLTF external resources must already be portable; GLB is usually easier to embed. Place the printed reference in the appropriate project field.

upgrade preserves identity, asset bytes, nested modules, and preview. Its output must be distinct and nonexistent; the original stays untouched. Unsafe paths, duplicate entries, size limits, corrupt archives, and unsupported versions fail before writing. extract, pack, and validate remain strict: supported older versions produce an upgrade command hint. For an old extracted workspace, upgrade its original .zq and extract again.

Successful validation:

{"ok":true,"schemaVersion":110,"issues":[],"simulation":{"capability":"disabled","definitions":0,"instances":0,"diagnostics":[]}}

Successful upgrade (example path):

{"ok":true,"sourceSchemaVersion":102,"targetSchemaVersion":110,"outputPath":"/work/current.zq","migrationWarnings":[]}

Failure with --json on upgrade or validate:

{"ok":false,"schemaVersion":110,"issues":[{"path":"project.json.version","message":"Unsupported project schema 100. Upgrade supports 101–110."}]}

Paths identify a JSON field, archive entry, workspace file, or argument where possible. Plain diagnostics go to stderr; success and JSON reports go to stdout. Exit 0 means success, 1 means validation or IO failure, and 2 means unknown command or invalid usage. Review non-fatal migration warnings before accepting a conversion. Validation cannot assess visuals or host device availability.

simulation reports the local host capability, authored definition and instance counts, and unsupported capability diagnostics. The format CLI can inspect and package valid simulation authoring records while its runtime capability is disabled. Production Portal uploads remain gated. An unsupported API or operation version stays in the file for editing; malformed references and invalid supported WGSL fail validation.