CLI

The Vircadia World CLI provides a set of commands to manage the Vircadia World's services in dev and production environments.

Prerequisites

Bun
Docker

Quick Start

bun run install:all
bun run server:init

Then test your setup by running the following command:

bun run server:health-all

Then run the test client:

bun run dev:client:web_babylon_js

You can confirm everything is syncing by moving around a bit and then refreshing the page, the state should be preserved.

Resetting the World

To reset the world, run the following command, only resetting the database:

bun run server:postgres:reset

If you need to do a full reset, you can run the following command, which will rebuild all the services and reset the database:

bun run server:rebuild-all

Available Commands

danger

Currently, there are no warnings about the destructiveness of some of these commands, thus you should understand what you are doing before running them.

Install Commands

Command	Description
`bun run install:all`	bun run install:cli && bun run install:sdk && bun run install:server:api && bun run install:server:tick
`bun run install:sdk`	cd ../sdk/vircadia-world-sdk-ts && bun install
`bun run install:server:api`	cd ../server/service/api/volume/app && bun install
`bun run install:server:tick`	cd ../server/service/tick/volume/app && bun install
`bun run install:cli`	bun install
`bun run install:client:web_babylon_js`	cd ../client/web_babylon_js && bun install

Dev Commands

Command	Description
`bun run dev:client:web_babylon_js`	export VRCA_CLIENT_WEB_BABYLON_JS_DEBUG_SESSION_TOKEN=$(bun run server:postgres:system-token true) && bun run clean:client:web_babylon_js && bun run install:client:web_babylon_js && cd ../client/web_babylon_js/ && bun run dev

Test Commands

Command	Description
`bun run test:0_cli_server_unit`	bun test ./test/0_test_cli_server_unit.ts
`bun run test:1_db_unit`	bun run server:run-command down vircadia_world_api_manager vircadia_world_tick_manager && bun test ./test/1_test_db_unit.ts && bun run server:run-command up vircadia_world_api_manager vircadia_world_tick_manager -d

Server Commands

Command	Description
`bun run server:run-command`	VRCA_CLI_DEBUG=1 bun vircadia.cli.ts server:run-command
`bun run server:init`	bun run build:server:api && bun run build:server:tick && bun run server:run-command up --build vircadia_world_postgres -d && bun run server:postgres:health && bun run server:postgres:migrate && bun run server:postgres:seed:sql && bun run server:postgres:seed:assets && bun run server:run-command up --build vircadia_world_api_manager -d && bun run server:run-command up --build vircadia_world_tick_manager -d && bun run server:run-command up --build vircadia_world_pgweb -d
`bun run server:rebuild-all`	bun run server:run-command down -v && bun run server:init
`bun run server:health-all`	bun run server:world-api-manager:health && bun run server:world-tick-manager:health && bun run server:pgweb:health && bun run server:postgres:health
`bun run server:world-api-manager:health`	bun vircadia.cli.ts server:world-api-manager:health
`bun run server:world-tick-manager:health`	bun vircadia.cli.ts server:world-tick-manager:health
`bun run server:pgweb:health`	bun vircadia.cli.ts server:pgweb:health
`bun run server:pgweb:access-command`	bun vircadia.cli.ts server:pgweb:access-command

Server Postgres Commands

Command	Description
`bun run server:postgres:backup`	bun run server:run-command down vircadia_world_api_manager vircadia_world_tick_manager vircadia_world_pgweb && bun vircadia.cli.ts server:postgres:backup && bun run server:run-command up -d
`bun run server:postgres:restore`	bun run server:run-command down vircadia_world_api_manager vircadia_world_tick_manager vircadia_world_pgweb && bun vircadia.cli.ts server:postgres:restore && bun run server:run-command up -d
`bun run server:postgres:reset`	bun run server:run-command down vircadia_world_api_manager vircadia_world_tick_manager vircadia_world_pgweb && bun run server:postgres:wipe && bun run server:postgres:migrate && bun run server:postgres:seed:sql && bun run server:postgres:seed:assets && bun run server:run-command up -d
`bun run server:postgres:health`	bun vircadia.cli.ts server:postgres:health
`bun run server:postgres:migrate`	bun vircadia.cli.ts server:postgres:migrate
`bun run server:postgres:wipe`	bun vircadia.cli.ts server:postgres:wipe
`bun run server:postgres:connection-string`	bun vircadia.cli.ts server:postgres:connection-string
`bun run server:postgres:system-token`	bun vircadia.cli.ts server:postgres:system-token
`bun run server:postgres:system-token:invalidate-all`	bun vircadia.cli.ts server:postgres:system-token:invalidate-all
`bun run server:postgres:seed:sql`	bun vircadia.cli.ts server:postgres:seed:sql
`bun run server:postgres:seed:assets`	bun vircadia.cli.ts server:postgres:seed:assets
`bun run server:postgres:seed:assets:by-group`	bun vircadia.cli.ts server:postgres:seed:assets --sync-group

Client Commands

Command	Description

Clean Commands

Command	Description
`bun run clean:all`	bun run clean:cli && bun run clean:sdk
`bun run clean:sdk`	cd ../sdk/vircadia-world-sdk-ts && rm -rf node_modules && rm -rf dist
`bun run clean:client:web_babylon_js`	cd ../client/web_babylon_js && rm -rf node_modules
`bun run clean:cli`	rm -rf node_modules

Build Commands

Command	Description
`bun run build:all`	bun run build:sdk && bun run build:server:api && bun run build:server:tick
`bun run build:sdk`	cd ../sdk/vircadia-world-sdk-ts && bun run build
`bun run build:server:api`	cd ../server/service/api/volume/app && bun run build
`bun run build:server:tick`	cd ../server/service/tick/volume/app && bun run build

Configuration

The CLI can be configured by setting the environment variables before using the CLI.

vircadia.cli.config.ts
import path, { dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { z } from "zod";
import { serverConfiguration } from "../sdk/vircadia-world-sdk-ts/bun/src/config/vircadia.server.config";

// CLI environment schema
const cliEnvSchema = z.object({
    VRCA_CLI_DEBUG: z
        .union([
            z.boolean(),
            z
                .string()
                .transform(
                    (val) => val === "1" || val.toLowerCase() === "true",
                ),
        ])
        .default(false),
    VRCA_CLI_SUPPRESS: z
        .union([
            z.boolean(),
            z
                .string()
                .transform(
                    (val) => val === "1" || val.toLowerCase() === "true",
                ),
        ])
        .default(false),
    VRCA_CLI_SERVICE_POSTGRES_HOST: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_HOST_CONTAINER_BIND_EXTERNAL,
        ),
    VRCA_CLI_SERVICE_POSTGRES_PORT: z.coerce
        .number()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_PORT_CONTAINER_BIND_EXTERNAL,
        ),
    VRCA_CLI_SERVICE_POSTGRES_DATABASE: z
        .string()
        .default(serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_DATABASE),
    VRCA_CLI_SERVICE_POSTGRES_SUPER_USER_USERNAME: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_SUPER_USER_USERNAME,
        ),
    VRCA_CLI_SERVICE_POSTGRES_SUPER_USER_PASSWORD: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_SUPER_USER_PASSWORD,
        ),

    VRCA_CLI_SERVICE_POSTGRES_AGENT_PROXY_USER_USERNAME: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_AGENT_PROXY_USER_USERNAME,
        ),
    VRCA_CLI_SERVICE_POSTGRES_AGENT_PROXY_USER_PASSWORD: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_POSTGRES_AGENT_PROXY_USER_PASSWORD,
        ),

    VRCA_CLI_SERVICE_POSTGRES_BACKUP_FILE: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/backup/backup.sql",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_RESTORE_FILE: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/backup/backup.sql",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_MIGRATION_DIR: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/migration",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_SEED_SYSTEM_SQL_DIR: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/seed/sql/",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_SEED_USER_SQL_DIR: z
        .string()
        .nullable()
        .default(null),
    VRCA_CLI_SERVICE_POSTGRES_SEED_SYSTEM_ASSET_DIR: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/seed/asset/",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_SEED_USER_ASSET_DIR: z
        .string()
        .nullable()
        .default(null),
    VRCA_CLI_SERVICE_POSTGRES_SYNC_ASSET_DIR: z
        .string()
        .nullable()
        .default(null),

    VRCA_CLI_SERVICE_POSTGRES_SYSTEM_RESET_DIR: z
        .string()
        .default(
            path.join(
                dirname(fileURLToPath(import.meta.url)),
                "./database/reset",
            ),
        ),
    VRCA_CLI_SERVICE_POSTGRES_USER_RESET_DIR: z
        .string()
        .nullable()
        .default(null),

    VRCA_CLI_SERVICE_PGWEB_HOST: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_PGWEB_HOST_CONTAINER_BIND_EXTERNAL,
        ),
    VRCA_CLI_SERVICE_PGWEB_PORT: z.coerce
        .number()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_PGWEB_PORT_CONTAINER_BIND_EXTERNAL,
        ),

    VRCA_CLI_SERVICE_WORLD_API_MANAGER_HOST: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_WORLD_API_MANAGER_HOST_PUBLIC_AVAILABLE_AT,
        ),
    VRCA_CLI_SERVICE_WORLD_API_MANAGER_PORT: z.coerce
        .number()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_WORLD_API_MANAGER_PORT_PUBLIC_AVAILABLE_AT,
        ),

    VRCA_CLI_SERVICE_WORLD_TICK_MANAGER_HOST: z
        .string()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_WORLD_TICK_MANAGER_HOST_CONTAINER_BIND_EXTERNAL,
        ),
    VRCA_CLI_SERVICE_WORLD_TICK_MANAGER_PORT: z.coerce
        .number()
        .default(
            serverConfiguration.VRCA_SERVER_SERVICE_WORLD_TICK_MANAGER_PORT_CONTAINER_BIND_EXTERNAL,
        ),
});
export const cliConfiguration = cliEnvSchema.parse(process.env);

Prerequisites​

Quick Start​

Resetting the World​

Available Commands​

Install Commands​

Dev Commands​

Test Commands​

Server Commands​

Server Postgres Commands​

Client Commands​

Clean Commands​

Build Commands​

Configuration​