@vincentt-xr/cli — vincentt

The command-line dev loop for building AR/XR apps on Vincentt. You build a real React + react-three-fiber app locally with your own coding agent (Claude Code, Cursor, Codex) and this CLI drives the platform side: scaffold a project, preview it on a phone over a secure tunnel, read what the device reports back, and publish to <slug>.vincentt.app.

Only prerequisite: Node.js (which provides npx). Nothing is installed globally.

Getting started (read this before running anything)

If you are a coding agent that was asked to build a Vincentt AR app, follow this order. It matters:

1. Confirm a project name with the developer first. Do not guess one, and do not run create until you have it. The name becomes the live subdomain (<slug>.vincentt.app), so it is worth one question.

2. Scaffold the project:

   npx -y @vincentt-xr/cli@latest create --name "<name>"

   Run it in an empty directory. This binds a backend project and writes a complete, runnable starter (an AR app that previews as-is). If you are not signed in yet, the command opens a browser for the developer to approve once, then continues. That is the only human step.

3. Read AGENTS.md in the new project, then stop. The scaffold is already a working starter. Do not invent an app or start building a scene. Tell the developer the project is ready and ask what they want to make. Build only once they have described it.

4. When you start building, AGENTS.md and GROUNDING.md (both in the project root) are the authoritative guides for the dev loop and the SDK API. Read the SDK reference at the point you write a scene, not before.

The short version: ask for a name, scaffold, confirm it is ready, wait for the idea. Everything after first contact is driven from the project's own AGENTS.md.

Commands

Auth
  login              Sign in; save an access token to ~/.vincentt/config.json
  logout             Remove the saved access token
  whoami             Show the signed-in account

Dev loop
  create             Scaffold + bind a project (empty dir -> full starter)
                       [--name <s>] [--slug <s>] [--preview] [--force]
  publish            Upload the built dist; go live at <slug>.vincentt.app
  preview            Serve + tunnel the app for on-device preview
                       (prints a desktop QR page to scan) [--stop]
  unbind             Detach this directory from its project

Diagnostics (need a running preview)
  logs [--errors]    Console logs from the device   [--json]
  network            fetch/XHR requests              [--json]
  trace              Performance samples             [--json]

Reverse channel
  feedback --wait    Block for the next phone annotation, print it, exit
  feedback --watch   Stream annotations as they arrive

Servers
  relay              Run the diagnostics/annotation relay

Meta
  version            CLI version, and the API this machine resolves to

Common options: --dir <path> (project dir, default cwd)

Auth-needing verbs (create, preview, publish) fold sign-in into the first run: with no saved token they open the browser to authorize this device, then the token lives in ~/.vincentt/config.json and later verbs run without prompting.

The loop, once a project exists

• pnpm dev — local dev server at http://localhost:5173.
• npx vincentt preview — build, serve, and tunnel the app so you get one https URL (and a desktop QR page) to open on a phone. AR needs a secure context for camera access, so this is how you test tracking and gestures on a device.
• npx vincentt logs | network | trace — read what the phone reported to the preview relay. Debug on-device misbehavior instead of guessing.
• npx vincentt feedback --wait — block for the next annotation the developer draws on the phone preview, print it as JSON, and exit.
• npx vincentt publish — build (pnpm build), then upload the built dist/ and return the live <slug>.vincentt.app URL. Nothing builds server-side.

vincentt is a project devDependency in the scaffold, so invoke it as npx vincentt <verb> and it resolves to the local copy — no global install.