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/mod-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 mod. The default is a public marketplace mod 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-mod              # tier A public React/R3F mod
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 mod id derives from the directory name (kebab-case enforced). Tier B scaffolds wire @vibelands/mod-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/mod-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.

To analyze the non-production manifest v3 proposal, pass --to 3:

vibelands migrate . --to 3 --dry-run --json
vibelands migrate . --to 3 --json

This never replaces vibelands-mod.json. It projects v2 permissions to finer draft capabilities and generates a separate draft manifest plus JSON Schema command/event contracts. Keep publishing with apiVersion 2 until the host promotes v3 from tooling draft to a supported runtime ABI.

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 mods 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_MOD_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 mods 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 mod into a fresh local Creator project. Creator assigns the explicit new mod 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 mod in a world you own. This is a mutating command: it updates that world's mod 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 mod 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 mod refs pinned in a world: mod 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.

sandbox [status|create|reset [--from <worldId>]|start|stop]

Shows and manages your Developer Sandbox: one private, 3-player hosted world per account, used only for mod development. Paid plans include it; free accounts can be granted one by the VibeLands team. It does not use a plan world slot and hibernates when nobody is inside, like any other hosted world.

vibelands sandbox                       # entitlement, world id, runtime, mods in development
vibelands sandbox reset --from my-island # replace its content with a copy of one of your worlds
vibelands sandbox reset                  # back to an empty island
vibelands worlds                         # sandbox status + world ids you can clone

Resetting discards what was built inside the sandbox, never changes the source world, and keeps mods under development attached.

serve <dir> [--clone-world <worldId>]

Uploads mod source into your Developer Sandbox — the only hosted place mods are tested. The sandbox is created on first use. --clone-world <worldId> first replaces the sandbox content with a copy of that world. Regular worlds are never used as preview targets; --direct-world was removed.

vibelands serve .
vibelands serve . --clone-world green-valley-copy
vibelands serve . --json

dev <dir> [--clone-world <worldId>] [--check-each] [--jsonl]

Watch mode built on serve: runs a full local check once, deploys to your Developer Sandbox, then watches the source tree and redeploys on every file change. --clone-world copies a world into the sandbox once before the first upload; later rebuilds keep the sandbox state. Game tabs that are already connected hot-swap the new bundle in place without a reload.

vibelands dev .
vibelands dev . --clone-world 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.

world <create|sandbox|pull|status|diff|push|unpack|pack>

Edits a whole world (settings, terrain, objects, missions and their scenes, races, roads, vehicles, mod list) as a Git-friendly file tree. The browser editor and the tree are two views of the same vibeworld v2 package.

vibelands world create my-island        # new empty island tree
vibelands world pull my-island --world-id <id> # hosted world (or --project <id> for a solo project)
vibelands world status my-island               # local edits since the pull, offline
vibelands world diff my-island                 # tree versus the server copy
vibelands world push my-island --dry-run       # print the plan, send nothing
vibelands world push my-island --yes           # replace the hosted world
vibelands world unpack dainava.vibeworld.json my-island
vibelands world pack my-island --out my-island.vibeworld.json

Layout:

Path	Holds
vibelands-world.json	world settings, mods, modLock, modData, assets, section versions
terrain/meta.json, terrain/pages/<px>,<pz>.json	editable terrain; 32x32 cells per page, one cell per line
objects/<sourceId>.json	one placed object per file; missions reference objects by sourceId
missions/index.json, missions/<id>/mission.json	mission order and each mission without its scenes
missions/<id>/intro.scene.json, outro.scene.json, steps/<step-id>.scene.json	mission scenes
races/index.json, races/<id>.json, roads.json, vehicles.json, sculpt.json	remaining sections; a missing file means null
.vibelands/	last pulled snapshot and server binding; ignored by Git

Object properties appear as JSON when that is lossless and stay a string otherwise. Objects without a usable sourceId are named _anon-<content hash>. File names never depend on the order the server returns rows in, so pulling an unchanged world leaves the tree byte-identical.

push targets hosted worlds only and replaces the whole world through the existing import route; the world runtime must be stopped. It refuses when the server copy changed after your last pull (--force overrides) and asks for the IMPORT <world-id> confirmation unless --yes is passed. Objects keep their IDs across pull and push; new objects receive a server ID and the tree is re-pulled after the push. pull and unpack refuse to overwrite local edits without --force. Pushing to a solo project is not available yet; pack the tree and import the file in the editor instead.

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

Submits a published sandbox build for marketplace review. This does not make the mod 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_MOD_SANDBOX_URL	login, doctor, serve, status, publish	hosted sandbox base URL; defaults to https://playvibelands.com
VIBELANDS_MOD_TOKEN	doctor, serve, status, publish	bearer token for hosted sandbox uploads, status/log reads, and review submissions