Skip to content
VGAI voxel logo VGAI Learn

Edit, upgrade & ship a project (CLI walkthrough)

cli tutorial Beginner ⏱ 10 min vgai 0.1.0

Prerequisites: Node.js installed

What you'll learn

  • Edit a world by editing its TSX source — there is no patch verb, and that is the point
  • See a bad edit reported loudly by validation rather than half-applied
  • Audit a project against its scaffold baseline with vgai upgrade --report
  • Dry-run a Cloudflare Pages deploy with vgai deploy --report

What you'll build: A scaffolded project taken through a source edit, a validation failure, an upgrade audit, and a staged (dry-run) deploy — all real captured output.

After scaffolding, a project’s life is: edit its source, then upgrade to audit and re-sync against the engine checkout, then deploy to ship it to Cloudflare Pages.

Note what is not in that list. There is no verb for “apply a validated edit to my world”, because a three root’s world is TSX source — so editing it is editing a file, with your editor, your agent, or the vgai editor’s viewport. The engine’s job is not to own a patch format; it is to tell you immediately and loudly when a save is broken.

# transcript pending capture — run: node site/media/capture-cli.mjs
Terminal — Edit, upgrade & ship a project (CLI walkthrough) · captured by site/media/capture-cli.mjs

Steps

Section titled “Steps”

  1. Scaffold a fresh project.

    Terminal window
    npx @vgai/cli@latest create lifecycle-demo

    Copies the editor template and installs dependencies (see Scaffold a project for details). What you get is a playable world — ground, ramp, pushable crates and a controllable character — authored in src/world.tsx. That is the file we’ll edit.

  2. Edit the world — it is just a file.

    The scaffold’s 3D world is src/world.tsx, and that file is the document. Adding a crate means adding JSX:

    <RigidBody colliders="cuboid" position={[2, 0.5, 0]}>
      <mesh castShadow receiveShadow>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="#ff5533" />
      </mesh>
    </RigidBody>

    Do that from a script, an agent, your editor, or by dragging in the vgai viewport — they all reach the same file. Because the props above are literals, the inspector can edit them and write the change back into this exact JSX element.

  3. A broken edit is reported, not half-applied.

    The dev server validates every save and reports failures in three places at once — the terminal, the editor console, and vgai status. Out of band, validate on demand:

    Terminal window
    npm run vgai -- validate

    This is the property the old patch verb existed to provide, relocated to where edits actually happen. A script can no longer half-apply a bad edit for the simple reason that there is no patch step to half-apply: a broken file fails to compile, loudly, at the save that broke it.

  4. Audit the project with npm run vgai -- upgrade --report.

    Terminal window
    npm run vgai -- upgrade --report

    upgrade compares every template file against the scaffold baseline (.vgai/scaffold-baseline.json) three-way: the edit from step 2 surfaces as a [user-edited] diff on src/world.tsx — reported, never clobbered. The engine pin is compared (here 0.2.0 -> 0.2.0 [match]) and the manifest/asset validation walls run. Drop --report to actually re-sync and re-pin.

  5. Dry-run the deploy.

    Terminal window
    npm run vgai -- deploy --report

    Discovery, the pre-flight walls, the production build, and staging all run — then it stops. Zero remote calls. The report names the Cloudflare Pages project (vgai-<slug>) and the URL shape it would ship to. Drop --report to push with wrangler.

Recap

New functionality

  • Added a crate by editing the world's TSX source
  • Validated the project and saw where a broken save is reported
  • Audited template drift and the engine pin with upgrade --report
  • Staged a full deploy with zero remote calls

New concepts & skills

  • a three root's world IS its source, so there is no patch verb and no separate document to keep in sync
  • validation moved to the save: the dev server reports failures to the terminal, the editor console and vgai status
  • upgrade is a three-way compare against the scaffold baseline — user edits are surfaced, never clobbered
  • deploy --report runs everything up to the wrangler push

Next lesson → Build & publish

See also

Section titled “See also”