Creator CLI Reference

vibelands is the VibeLands Creator command: scaffold, validate, preview, test, publish, and install multiplayer world features through VibeLands-hosted infrastructure.

Commands with --json or --jsonl keep stdout machine-readable. Fatal errors are emitted as one JSON object on stderr with code, stage, message and a safe next action; stored developer tokens are never included.

Install Creator

npm install --global @vibelands/creator
vibelands --help

The Creator package installs its compatible @vibelands/plugin-sdk dependency automatically. Generated projects pin both packages to the matching compatibility line, so npm install is enough outside the VibeLands monorepo.

create <dir> [--template id] [--tier A|B] [--runtime public|internal] [--json]

Scaffold a working plugin. The default is a public marketplace plugin with a React/R3F client entry. --runtime internal creates a first-party/workspace variant. Every scaffold also includes AGENTS.md for a local LLM and review-metadata.json for marketplace review submission details.

vibelands create my-plugin              # tier A public React/R3F plugin
vibelands create my-quest --tier B      # + server entry + headless test (npm test)
vibelands create my-props --template props-pack
vibelands create my-game --template persistent-collectible
vibelands create my-pack --runtime internal
vibelands create agent-project --json   # machine-readable paths, versions and next commands

The plugin id derives from the directory name (kebab-case enforced). Tier B scaffolds wire @vibelands/plugin-sdk and vitest as devDependencies so npm install && npm test works immediately.

Use vibelands templates --json to list the installed, version-matched capability starters. Current templates cover deterministic atmosphere, placeable prop packs, persistent nearby interactions, inventory/crafting and authoritative physics entities.

vibelands examples --capability <term> --json filters those local examples by API or capability. Add --marketplace to include matching open-source Marketplace listings, permissions and an exact remix command. Marketplace failure never removes the installed offline examples.

context <dir> [--json]

Reads the local manifest and package metadata, validates entry paths, and reports the exact installed Creator/SDK/apiVersion contract. JSON includes tier, runtime, entries, permissions, scripts, project files, shared modules, budgets, content limits, permission-to-API mappings, canonical recipes, the installed SDK export inventory and canonical docs links.

vibelands context .
vibelands context . --json
vibelands context . --format agent-md
vibelands context . --write

Use this as the first discovery command for a local LLM instead of asking it to guess capabilities from host source.

--format agent-md prints a prompt-friendly Markdown contract. --write [relative-file] writes it under the project (.vibelands/CONTEXT.md by default).

migrate <dir> [--dry-run] [--json]

Upgrades a supported older manifest/SDK contract. The apiVersion 1 → 2 migration updates the manifest and portable Creator/SDK dependencies only when source scanning finds no raw physics imports. Projects using @react-three/rapier, @dimforge/rapier3d-compat or @vibelands/physics receive file/line diagnostics and must move to @vibelands/plugin-sdk/physics first.

vibelands migrate . --dry-run --json
vibelands migrate . --json
npm install
npm run check

Unknown migration paths fail closed rather than changing the apiVersion without a known source transformation.

check <dir> [--review]

Static validation + dry builds where entries exist (nothing written):

✔ my-quest@0.1.0 (tier B) - manifest OK
  dist/client.js  14.2 kB (5.1 kB gzip)
✔ client entry builds clean (no host-internal imports, no singleton copies, within budget)
✔ server entry builds clean
  assets/         2.31 MB
✔ my-quest passed all checks

Catches: invalid manifest fields, public plugins without entries.client, unknown permissions, bad configSchema fields, missing entry files, compile errors, imports of @vibelands/client|server|shared, bundled copies of shared singletons, gzip/asset budget violations.

Add --review before publishing. It loads review-metadata.json by default or the file passed with --metadata, checks marketplace description, tags, license, support URL, privacy notes, and permission rationale, and exits nonzero while any review fields are missing or still placeholder text.

vibelands check . --review
vibelands check . --review --metadata review-metadata.json --json

login [--remote <url>] [--no-open] [--json|--jsonl]

Starts a browser-confirmed device login:

vibelands login

Creator requests a short-lived code, prints the complete confirmation URL and the code, opens the browser when possible, and polls while you review the request. The browser requires a registered VibeLands account and displays the same code before allowing Confirm and connect or Deny. Approval creates a separate 30-day creator-cli session; the existing browser session token is never placed in the URL, terminal, or Creator output.

Use --no-open on SSH/headless machines and open the printed URL elsewhere. --jsonl emits an authorization_required event followed by an authenticated event, which is useful when Creator Studio needs to present the link without reading any credential. --json opens the browser and emits one final result after confirmation.

--token <token> remains an explicit non-default fallback for CI or legacy automation. Prefer VIBELANDS_PLUGIN_TOKEN for ephemeral CI secrets and never put either form in an LLM prompt.

doctor

Runs a preflight check before your first hosted sandbox upload:

• remote /health reachability;
• whether a Creator account session is configured;
• whether the authenticated account has hosted worlds available for sandbox testing.

vibelands doctor
vibelands doctor --json
vibelands doctor --remote https://playvibelands.com

The command exits nonzero when a required check fails. --json emits ok, remote, tokenConfigured, worlds, and per-check diagnostics without printing the token value.

worlds

Lists hosted worlds you can use as sandbox targets:

vibelands worlds

reviews

Lists your marketplace review submissions, status, submission URL, and reviewer notes when available. If the hosted review API found missing marketplace metadata, the command also prints review metadata warnings.

vibelands reviews
vibelands reviews --json

review <submissionId>

Shows one marketplace review submission in detail: build id, status URL, changelog, review metadata warnings, reviewer notes, and automated report log link when available.

vibelands review 11111111-2222-4333-8444-555555555555
vibelands review 11111111-2222-4333-8444-555555555555 --json

marketplace [query]

Searches published marketplace plugins without mutating any world. Use it after a review is approved to verify that the listing is publicly discoverable.

vibelands marketplace
vibelands marketplace farming
vibelands marketplace farming --json

marketplace:show <slug>

Shows one marketplace listing with latest version, permissions, tags, ratings, description, and published versions.

vibelands marketplace:show farming
vibelands marketplace:show farming --json

remix <slug> <dir> --id <newId>

Downloads the text source of an open-source Marketplace plugin into a fresh local Creator project. Creator assigns the explicit new plugin id, resets version/author/review metadata, records forkedFrom, normalizes portable package dependencies and writes a new AGENTS.md.

vibelands remix community-board my-board --id my-board
vibelands remix community-board my-board --id my-board --json

The target must be empty or missing. Closed-source listings are rejected, and the source endpoint intentionally does not copy binary assets.

marketplace:install <slug> --world-id <worldId>

Installs or updates a published marketplace plugin in a world you own. This is a mutating command: it updates that world's plugin refs through the hosted control plane and applies live when the room is running. Passing --version pins that version, so the same command is also the rollback path.

vibelands marketplace:install farming --world-id my-world
vibelands marketplace:install farming --world-id my-world --version 1.2.0
vibelands marketplace:install farming --world-id my-world --config config.json
vibelands marketplace:install farming --world-id my-world --config-json '{"density":1.5}'
vibelands marketplace:install farming --world-id my-world --disabled

The command requires a stored session token from vibelands login.

marketplace:uninstall <slug> --world-id <worldId>

Removes a published marketplace plugin from a world you own and live-applies the change when the room is running.

vibelands marketplace:uninstall farming --world-id my-world
vibelands marketplace:uninstall farming --world-id my-world --json

The command requires a stored session token from vibelands login.

marketplace:world --world-id <worldId>

Shows the current plugin refs pinned in a world: plugin id, version, enabled state, and config. Use it after install, rollback, or uninstall.

vibelands marketplace:world --world-id my-world
vibelands marketplace:world --world-id my-world --json

The command requires a stored session token from vibelands login.

status <buildId> [--logs]

Fetches a sandbox build after serve or publish, prints the current build state, artifact/log links, sandbox world/runtime details, and any runtime preparation error. Add --logs to include the hosted build log tail.

vibelands status 11111111-2222-4333-8444-555555555555
vibelands status 11111111-2222-4333-8444-555555555555 --logs --log-lines 120
vibelands status 11111111-2222-4333-8444-555555555555 --json

--json returns the same machine-readable sandbox summary used by serve --json. With --json --logs, the response includes logTail.

inspect <buildId> [--json]

Performs a read-only agent handoff check for a hosted build: published status, live runtime, exact applied revision, sandbox errors and suspicious log-tail errors. JSON includes stable checks/diagnostics plus a separate visualVerification object with the game URL and browser assertions.

vibelands inspect 11111111-2222-4333-8444-555555555555 --json

This command does not claim that a scene looks correct. It proves that the hosted revision is ready for browser inspection and states what still needs to be observed.

serve <dir> [--world-id <id>] [--direct-world]

Uploads plugin source into the VibeLands-hosted sandbox. If --world-id is omitted, the CLI shows an interactive list of your hosted worlds. By default the plugin runs in a temporary clone of the selected world. --direct-world is an explicit opt-in that runs the sandbox plugin against the original world.

vibelands serve .
vibelands serve . --world-id green-valley-copy
vibelands serve . --world-id green-valley-copy --direct-world
vibelands serve . --json

dev <dir> [--world-id <id>] [--check-each] [--jsonl]

Watch mode built on serve: runs a full local check once, deploys to the hosted sandbox, then watches the source tree and redeploys on every file change. The sandbox world is stable per plugin, so game tabs that are already connected hot-swap the new bundle in place without a reload.

vibelands dev .
vibelands dev . --world-id green-valley-copy
vibelands dev . --check-each        # full local check before each upload
vibelands dev . --debounce-ms 800   # coalesce rapid saves (default 400)

By default iterations skip the local dry build for speed - the hosted builder still validates, scans, and signs every upload. Use --check-each to fail fast locally instead.

--jsonl is the agent/automation mode. Every stdout line is one JSON event: initial check, build start, upload, live/failed result, and watch start/stop. Failures include a stage and message; live events include build identity, duration, game URL and sandbox diagnostics.

publish <buildId|dir> [--metadata file.json]

Submits a published sandbox build for marketplace review. This does not make the plugin public immediately.

vibelands publish 11111111-2222-4333-8444-555555555555
vibelands publish . --metadata review-metadata.json
vibelands publish . --changelog "Initial review submission"

When passed a directory, publish validates, uploads, waits for the hosted build to reach published, then creates the review submission.

--metadata must point to a JSON object. Supported fields are description, tags, media, license, supportUrl, privacyNotes, permissionRationale, testNotes, and changelog. Manifest fields provide fallbacks for description, tags, license, and author supportUrl when publishing from a directory. Required review fields fail the readiness check and are enforced by the hosted review API; missing media or reviewer test notes remain recommendations.

Environment variables

Variable	Used by	Purpose
VIBELANDS_PLUGIN_SANDBOX_URL	login, doctor, serve, status, publish	hosted sandbox base URL; defaults to https://playvibelands.com
VIBELANDS_PLUGIN_TOKEN	doctor, serve, status, publish	bearer token for hosted sandbox uploads, status/log reads, and review submissions