> For the complete documentation index, see [llms.txt](https://voyzu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voyzu.gitbook.io/docs/voyzu-platform-guide/commands.md).

# 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`                                 | <p><code>Example: npm run voyzu:initialize</code><br><br>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 <code>.env.local</code> and before installing packages. See <a href="/pages/D5Q7oMLpA7oNTdyrqloD">Production installation and setup</a>.</p> |
| Install a package | `npm run voyzu:install -- <github-address> <package-name>` | <p><code>Example: npm run voyzu:install -- <https://github.com/chrisjameslennon/voyzu-packages.git> @voyzu/ice-creams</code><br><br>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.</p>                                                                                                                            |
| Start Voyzu       | `npm run voyzu:start`                                      | <p><code>Example: npm run voyzu:start</code><br><br>Builds the production application through the root <code>prestart</code> hook and starts the Next.js server. <code>npm start</code> is also supported.</p>                                                                                                                                                                                                                                                                             |

## 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`                                                     | <p><code>Example: npm run voyzu:update</code><br><br>Requires the platform checkout to be on <code>main</code>, discards generated composition output, refuses to continue if the downloaded platform contains other local changes, fast-forwards Voyzu with <code>git pull --ff-only</code>, 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.<br>Restart the web server to apply the changes.</p> |
| Add a repository                                  | `npm run voyzu:add-repo -- <github-address>`                               | <p><code>Example: npm run voyzu:add-repo -- <https://github.com/example/fred-packages.git></code><br><br>Shallow-clones a package repository beneath <code>.package-sources</code> without installing a package.</p>                                                                                                                                                                                                                                                                                                                                                                                                     |
| Update all repositories                           | `npm run voyzu:update-repos`                                               | <p><code>Example: npm run voyzu:update-repos</code><br><br>Runs <code>git pull --ff-only</code> in every downloaded package repository. It does not update installed package copies.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Update one repository                             | `npm run voyzu:update-repo -- <repository-name>`                           | <p><code>Example: npm run voyzu:update-repo -- voyzu-packages</code><br><br>Runs <code>git pull --ff-only</code> in one downloaded package repository. It does not update the installed package copy.</p>                                                                                                                                                                                                                                                                                                                                                                                                                |
| Install a package from downloaded source          | `npm run voyzu:install-package -- <package-name>`                          | <p><code>Example: npm run voyzu:install-package -- @voyzu/ice-creams</code><br><br>Copies the named package from an already downloaded repository beneath <code>.package-sources</code> into <code>.run/packages</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                             |
| Uninstall a package                               | `npm run voyzu:uninstall-package -- <package-name>`                        | <p><code>Example: npm run voyzu:uninstall-package -- @voyzu/ice-creams</code><br><br>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.</p>                                                                                                                                                                                                                                                                      |
| List installed packages                           | `npm run voyzu:list-packages`                                              | <p><code>Example: npm run voyzu:list-packages</code><br><br>Lists every Voyzu package present beneath <code>.run/packages</code>, including its version. This command is also available in a development runtime.</p>                                                                                                                                                                                                                                                                                                                                                                                                    |
| Compose packages                                  | `npm run voyzu:compose`                                                    | <p><code>Example: npm run voyzu:compose</code><br><br>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.</p>                                                                                                                                                                                                                                                                                                                                      |
| Run a package script                              | `npm run voyzu:run-script -- <package-name> <script-name> [parameters...]` | <p><code>Example: npm run voyzu:run-script -- @voyzu/ice-creams sampleData</code><br><br>Executes a callable script exported through the installed package's <code>voyzu.package.ts</code> scripts object.</p>                                                                                                                                                                                                                                                                                                                                                                                                           |
| Build Voyzu                                       | `npm run voyzu:build`                                                      | <p><code>Example: npm run voyzu:build</code><br><br>Creates a production Next.js build without starting the server.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Build the API Reference                           | `npm run voyzu:build-api-reference`                                        | <p><code>Example: npm run voyzu:build-api-reference</code><br><br>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.</p>                                                                                                                                                                                                                                                                                                                         |
| Run a production installation in development mode | `npm run voyzu:dev`                                                        | <p><code>Example: npm run voyzu:dev</code><br><br>Starts the generated production installation with the Next.js development server. Installed packages remain copied rather than live-linked.</p>                                                                                                                                                                                                                                                                                                                                                                                                                        |

## 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>`                                            | <p><code>Example: npm run voyzu:create-package -- "@acme/customer orders"</code><br><br>Creates <code>@acme/customer-orders</code> from the Ice Creams reference package beneath the root <code>packages</code> 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, <code>@acme/widgets</code> uses <code>Widgets</code>, <code>Widget</code> and the <code>widgets</code> table. It then links the new package into the development runtime. The root <code>packages</code> directory and an initialized Voyzu database must already exist.</p> |
| Link one local package       | `npm run voyzu:link-package -- <package-name>`                                              | <p><code>Example: npm run voyzu:link-package -- @voyzu/ice-creams</code><br><br>Installs one installable local package from <code>packages/@publisher/package-name</code> as a physical copy beneath <code>.run/packages</code>. It installs dependencies, applies package SQL and composes the application. While <code>npm run dev</code> is running, Voyzu watches the matching source package and mirrors changes into this runtime copy.</p>                                                                                                                                                                                                                                                              |
| Link all local packages      | `npm run voyzu:link-packages`                                                               | <p><code>Example: npm run voyzu:link-packages</code><br><br>Installs every installable package in the root <code>packages</code> workspace as physical runtime copies, then installs dependencies, applies package SQL and composes once. While <code>npm run dev</code> is running, matching packages are watched and synchronized.</p>                                                                                                                                                                                                                                                                                                                                                                       |

For the complete development workflow, see [Development setup](/docs/voyzu-platform-guide/development-setup.md).