# @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.