Commands

Production commands

Run these first-class commands from the root of a generated Voyzu installation.

Command	Full command	Description
Initialize Voyzu	npm run voyzu:initialize	Example: npm run voyzu:initialize Initializes the preinstalled platform packages in Voyzu's predefined dependency order, then builds the platform. The current order is Foundation, Authentication and Users, Package Management, Audit, Welcome, UI Reference, then API Reference. Run this command after configuring .env.local and before installing packages. See Production installation and setup.
Install a package	npm run voyzu:install -- <github-address> <package-name>	Example: npm run voyzu:install -- https://github.com/chrisjameslennon/voyzu-packages.git @voyzu/ice-creams Downloads the repository when absent or refreshes its existing checkout, installs the named package, applies its SQL, installs workspace dependencies, and composes the application. Voyzu must already be initialized.
Start Voyzu	npm run voyzu:start	Example: npm run voyzu:start Builds the production application through the root prestart hook and starts the Next.js server. npm start is also supported.

Other production commands

These commands provide more granular control when needed. Run them from the root of a Voyzu installation.

Command	Full command	Description
Update Voyzu	npm run voyzu:update	Example: npm run voyzu:update Requires the platform checkout to be on main, discards generated composition output, refuses to continue if the downloaded platform contains other local changes, fast-forwards Voyzu with git pull --ff-only, and recomposes the installed packages. Composition installs the current workspace dependencies and rebuilds the API reference. A production runtime is then rebuilt; a development runtime skips the production build. It does not run package SQL or package scripts. Restart the web server to apply the changes.
Add a repository	npm run voyzu:add-repo -- <github-address>	Example: npm run voyzu:add-repo -- https://github.com/example/fred-packages.git Shallow-clones a package repository beneath .package-sources without installing a package.
Update all repositories	npm run voyzu:update-repos	Example: npm run voyzu:update-repos Runs git pull --ff-only in every downloaded package repository. It does not update installed package copies.
Update one repository	npm run voyzu:update-repo -- <repository-name>	Example: npm run voyzu:update-repo -- voyzu-packages Runs git pull --ff-only in one downloaded package repository. It does not update the installed package copy.
Install a package from downloaded source	npm run voyzu:install-package -- <package-name>	Example: npm run voyzu:install-package -- @voyzu/ice-creams Copies the named package from an already downloaded repository beneath .package-sources into .run/packages.
Uninstall a package	npm run voyzu:uninstall-package -- <package-name>	Example: npm run voyzu:uninstall-package -- @voyzu/ice-creams Requires the Next.js runtime to be stopped, runs the package's uninstall script, removes its runtime copy, and recomposes Voyzu. The package's uninstall script may permanently delete package data. Preinstalled platform packages cannot be uninstalled.
List installed packages	npm run voyzu:list-packages	Example: npm run voyzu:list-packages Lists every Voyzu package present beneath .run/packages, including its version. This command is also available in a development runtime.
Compose packages	npm run voyzu:compose	Example: npm run voyzu:compose Regenerates navigation, page routes, API routes, workspace dependencies, Next.js package configuration, package-grouped API operation documents, and the combined OpenAPI document from the currently installed packages.
Run a package script	npm run voyzu:run-script -- <package-name> <script-name> [parameters...]	Example: npm run voyzu:run-script -- @voyzu/ice-creams sampleData Executes a callable script exported through the installed package's voyzu.package.ts scripts object.
Build Voyzu	npm run voyzu:build	Example: npm run voyzu:build Creates a production Next.js build without starting the server.
Build the API Reference	npm run voyzu:build-api-reference	Example: npm run voyzu:build-api-reference Regenerates the package-grouped API operation documents and the single combined OpenAPI document from the API definitions in preinstalled and installed packages. This command is also available in a development runtime.
Run a production installation in development mode	npm run voyzu:dev	Example: npm run voyzu:dev Starts the generated production installation with the Next.js development server. Installed packages remain copied rather than live-linked.

Development commands

These commands are available only in a development runtime created with create-voyzu dev in an existing development workspace.

Command	Full command	Description
Recreate development runtime	npm exec --yes --package=github:chrisjameslennon/create-voyzu -- create-voyzu dev --force	Stop the web server before running this command. It deletes and recreates the entire .run directory, downloads Voyzu from main, and reinstalls runtime dependencies. Root package source beneath packages, .package-sources, .env.local, .gitignore, the root package.json, and database data are preserved. Runtime copies of installed packages are removed, so link or install them again afterward.
Create a local package	npm run voyzu:create-package -- <package-name>	Example: npm run voyzu:create-package -- "@acme/customer orders" Creates @acme/customer-orders from the Ice Creams reference package beneath the root packages workspace. Spaces are replaced with dashes. The command removes the template Git metadata and derives display labels, code identifiers, paths and SQL table names from the segment after the author. For example, @acme/widgets uses Widgets, Widget and the widgets table. It then links the new package into the development runtime. The root packages directory and an initialized Voyzu database must already exist.
Link one local package	npm run voyzu:link-package -- <package-name>	Example: npm run voyzu:link-package -- @voyzu/ice-creams Installs one installable local package from packages/@publisher/package-name as a physical copy beneath .run/packages. It installs dependencies, applies package SQL and composes the application. While npm run dev is running, Voyzu watches the matching source package and mirrors changes into this runtime copy.
Link all local packages	npm run voyzu:link-packages	Example: npm run voyzu:link-packages Installs every installable package in the root packages workspace as physical runtime copies, then installs dependencies, applies package SQL and composes once. While npm run dev is running, matching packages are watched and synchronized.

For the complete development workflow, see Development setup.