Command-line reference

Available executable

The worldpack executable builds and inspects portable world data. The qway alias also deploys that data as the complete static host site to Ubuntu/Nginx. After building the repository, run:

node packages/worldpack-cli/dist/cli.js --help

The package exposes both worldpack and qway bins. In this repository, deploy builds the bundled static frontend automatically; outside it, provide an already-built site with --site-dir.

Build a package

worldpack build project.json --data ./data -o ./world.worldpack
worldpack build project-directory --data ./data --out ./world.worldpack --resolved --debug

A directory input resolves project.json. --data and -o/--out are required. Normal build compiles pinned inputs once; --resolved packages accepted resolved data without recompilation. --debug includes supported debug material. --entry-room selects an entry room identity when supported by the world. Outputs are exclusive: choose a new filename, not an overwrite target. Invalid drafts or missing immutable dependencies fail.

Verify, inspect, explode, serve

worldpack verify world.worldpack
worldpack inspect world.worldpack
worldpack explode world.worldpack -o ./new-world-directory
worldpack serve world.worldpack --port 8080 --origin http://localhost:5173

verify emits compact JSON; inspect emits readable JSON including manifest/license information. Both verify the complete archive. explode requires a new output directory. serve is loopback-only, defaults to port 8080, supports an explicit CORS origin, and stops on SIGINT/SIGTERM. It does not publish or authenticate a world.

Deploy the static host site

qway deploy ./workshop.worldpack --host deploy@ubuntu.example.com --domain world.example.com --email admin@example.com
qway deploy ./workshop.worldpack --www --staging
qway deploy ./workshop.worldpack --dry-run

In the repository, deploy builds the bundled static host site, replaces its /world/ resources with the verified input WorldPack, and ships the complete site over SSH/SCP. Missing host, domain and contact email are prompted in an interactive terminal. The remote host must be Ubuntu with passwordless sudo; DNS and ports 80/443 must be ready for Certbot. Nginx uses sites-available/sites-enabled, serves hashed WorldPack resources as immutable and revalidates the manifest. HTTPS redirects from HTTP and certificate renewal is enabled. Existing releases are retained. --www includes the www host in DNS and the certificate; --staging uses a test certificate; --dry-run assembles and checks locally without connecting.

Options and exit behavior

Unknown or duplicate options are errors. --help (or no arguments) prints usage and exits 0. Successful commands exit 0; failures print a message to stderr and exit 1. No structured JSON error protocol is promised. The generated help snapshot below is checked against the executable.

Repository commands

make install
make dev
make test
make e2e
make lint
make typecheck
make build
make integrity
npm run regression
npm run docs:build
npm run docs:check

make integrity inspects the configured data root; it is not a migration or repair command. make smoke-openai is opt-in live provider testing and needs credentials. The permanent regression gate protects private data and compares historical test floors.

Executable help snapshot

qway deploy <file.worldpack> [--host user@ubuntu] [--domain example.com] [--email admin@example.com] [--site-dir ./site/dist] [--www] [--staging] [--dry-run]
worldpack build <project.json|directory> --data <data-root> -o <file.worldpack> [--resolved] [--debug] [--entry-room UUID] [--speech-api http://127.0.0.1:8000/api/v2]
worldpack verify|inspect <file.worldpack>
worldpack install <file.worldpack> -o <new-static-site>
worldpack explode <file.worldpack> -o <new-directory>
worldpack serve <file.worldpack> [--port 8080] [--origin http://localhost:5173]

Copy/paste CLI exercise

Download the complete fixture project and data directory, unzip into a new directory, and run these commands with the installed worldpack executable on PATH. All four non-server commands are exercised by docs:check. The output names must not already exist.

worldpack build project.json --data data -o workshop.worldpack
worldpack verify workshop.worldpack
worldpack inspect workshop.worldpack
worldpack explode workshop.worldpack -o exploded
worldpack serve workshop.worldpack --port 8080 --origin http://localhost:5173

Serve is long-running; stop with Ctrl+C. No API credentials are used. The fixture data directory is separate from your Studio data, so this exercise cannot revise your saved projects.