npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@vincentt-xr/cli

v0.28.1

Published

Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)

Readme

@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. Create the project:

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

    In an empty folder this writes a complete, runnable starter (an AR app that previews as-is), installs its dependencies, and then registers the project and reserves its address. In a folder that is already a Vincentt app it only registers. In any other non-empty folder it refuses and says what to run.

    The scaffolding half needs no account. The registering half does: 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, create, confirm it is ready, wait for the idea. Everything after first contact is driven from the project's own AGENTS.md.

Commands

init needs no account, ever — the template is yours to scaffold and run locally whether or not you sign in. create also scaffolds an empty folder, and then registers the project, which is what needs an account.

Auth
  login              Sign in this machine; save an access token to ~/.vincentt/config.json
                       [--label <name>] names this machine (default: OS, arch, date)
  logout             Sign this machine out and remove the saved access token
  whoami             Show the signed-in account

Project
  init [dir]         Scaffold a Vincentt XR app — no account needed, ever
                       [--no-install] [--template <version>]
  clone <dir>        Copy a gallery template (needs an account)
                       [--gallery <id>] [--name <s>] [--slug <s>]
  create [name]      Register a project and reserve its address; scaffolds first
                       if the folder is empty
                       [--name <s>] [--slug <s>] [--org <s>] [--preview]
                       [--force] [--no-install]
  link <project-id>  Link this directory to an existing project; for an app not
                       made from the template, also writes vincentt.json
                       [--json] [--dev-command <cmd>] [--dev-port <n>]
                       [--build-command <cmd>] [--build-output <folder>]
  unlink             Detach this directory from its project
  projects           List the workspace's projects, their ids, and where each
                       one lives on this machine
                       [--json] [--org <s>]

Dev loop
  publish            Upload the built dist; go live at <slug>.vincentt.app
                       [--dist <folder>] (relative to the project folder)
                       [--yes] [--json]
  preview            Serve + tunnel the app for on-device preview
                       (prints a desktop QR page to scan) [--stop]
                       [--port <n>] [--dev-command <cmd>]

Project source (stored on Vincentt; syncs only when asked)
  push               Save what changed since the last pull as a new version
                       and print its check  [--note <s>] [--json]
  pull               Make this folder match the stored version
                       [--discard-local] [--accept-runnable <file,file>] [--json]
  source export      Download the stored source as a zip
                       [--version <n>] [--out <file>] [--json]
  source disable     Delete the copy stored on Vincentt (owners, at a terminal,
                       typing the project's address)

Test links (a frozen copy of one version, for a client)
  test-link          7 days or 100 views, whichever comes first
                       [--version <n>] [--passcode] [--json]

Comments (saved by workspace members in the console)
  comments           This folder's project's open comments, one JSON object
                       per line  [--state open|resolved|all]
  comments <n>       One comment with its replies; its picture is saved to
                       .vincentt/comments/<n>.png
  comments <n> --reply "<text>"   Reply  [--resolve] closes it too

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)

Start from a gallery template

Each template's page in the console shows the command that copies it:

vincentt clone tic-tac-toe --gallery 0123456789abcdef01234567

Sign-in comes first, and nothing is written before it: without a saved token the command opens the browser to authorize this device (at a terminal) or refuses and names vincentt login (without one). The folder must be new or empty. The CLI downloads the version of the template Vincentt approved, checks every file against its hash before writing it, and then registers the project like create. It never installs dependencies and never runs git; the folder is not a git repository until you run git init. init and create refuse --gallery and name this command.

Auth-needing verbs (create's registering half, 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. init never reaches that gate at all.

Project source

A new project's source is stored on Vincentt: when create scaffolds a new project it uploads the folder as version #1 (registering an existing folder uploads nothing until you push), and the console and connected AI apps read and save the same versions. Nothing else syncs on its own.

  • vincentt push sends what changed since the last pull as one new version and prints its check (syntax errors, packages outside the shared runtime, broken imports). A failed check is a report; the version is still saved. When someone saved since this folder last pulled, the push is refused and names who and where: run vincentt pull first. When another save is still finishing, push waits and tries again on its own.
  • What push never sends: symbolic links (never followed), .git, the .vincentt folder, and anything git would ignore (every .gitignore, .git/info/exclude and your global excludes file). It refuses, by name, .env files, private keys, credential files (including .git-credentials and Terraform state), installed packages and build output that are not gitignored, and the platform refuses a file holding a secret key, naming the file and line.
  • vincentt pull writes the stored version into this folder. It is refused over unpushed changes; --discard-local moves them into .vincentt/discarded/<time>/ (push never reads it) rather than deleting them. It never writes through a link, never touches .git, leaves files this folder gitignores alone, and never writes over a local file Vincentt has never seen.
  • Pull lists any change to a file that can run code on this computer and asks first: any package.json change other than a registry version bump of a dependency it already had, any lockfile (package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml, yarn.lock, bun.lock, bun.lockb), pnpm-workspace.yaml, package.yaml and package.json5, *.config.js / .ts / .mjs / .cjs files, lint-staged and commitlint config, bunfig.toml, git hook managers, any hidden file or folder such as .vscode/ or an AI tool's settings, and upper-case instruction files such as AGENTS.md. Without a terminal it holds them back and lists them: show the person the list and ask. When they agree, name exactly those files: vincentt pull --accept-runnable package.json,.vscode/tasks.json. A bare --accept-runnable is refused, and any held-back file not named stays held back.
  • The one exception: a first pull into an empty folder (no sync record, and nothing at all on disk apart from .vincentt and .git) writes those files too and lists them as "can run code: review before installing". A folder with any stray file, even an ignored one, gets the usual hold-back.
  • The sync point lives in .vincentt/source.json, inside the gitignored binding folder, and names its project: after a re-link it no longer counts.
  • vincentt publish on such a project pushes first, then publishes that version, built on Vincentt. A project not on the shared runtime, or one using packages outside it, is built here and its output uploaded.
  • vincentt source export downloads a version as a zip. vincentt source disable deletes the stored copy; it is owner-only, runs only at a terminal, and asks you to type the project's address. This folder is never touched.

Test links

vincentt test-link makes a frozen copy of one version for a client, at its own random *.vincentt.dev address. It lasts 7 days or 100 views, whichever comes first (higher on paid plans); reloads in one browser session count once. It keeps working when nothing runs on this computer.

$ vincentt test-link
→ Glow Filter source is hosted: making a test link from #41 (latest clean save)
✓ https://m2n3b4v5c6x7z2a3s4d5f6g7h2j3k4l5.vincentt.dev
  7 days or 100 views · no passcode
  • On a project whose source is stored on Vincentt the link is made on Vincentt from the latest clean save, or from the saved version --version <n> names. Changes in this folder that were never pushed are not in it: vincentt push first.
  • A hosted project the platform can't build (not on the shared runtime, or using packages outside it) is built from this folder instead, as publish decides it. The link then names no save and may differ from the last one, and the command says so.
  • Any other project is built here, checked exactly as publish checks its output (hidden files, keys and credentials, links leaving the folder, size limits), and uploaded. Publish's link-preview and root-path warnings are printed first; they never block.
  • --passcode asks for a passcode of at least 6 characters at the terminal and shows nothing as it is typed. It is never taken as an argument, so it never lands in shell history; without a terminal the command refuses before sending anything. Flags other than --passcode, --version, --json, --dir, --api and --allow-custom-api are refused unread.
  • When a passcode was asked for and the platform's answer does not confirm it, the command fails and says to end that link in the console: it is never shown as a link to send.
  • A workspace has at most 10 live test links on Free (50 on paid) and makes at most 20 a day. At the cap, end one in the console or wait for one to expire. Links are ended early in the console.

Comments

Workspace members leave comments on a project's preview in the console: a paused frame, marked up, with a message. Each comment is numbered per project (#12) and kept until a member deletes it. vincentt comments is the terminal way in for an agent; the console's "Copy for agent" line names the number and the project id.

$ vincentt comments                      # stdout: one JSON object per open comment
$ vincentt comments 12                   # the comment, its replies, its picture
$ vincentt comments 12 --reply "Moved the title up 40px" --resolve
  • Only the project this folder is linked to. --project <id> is accepted only when it names that project; any other is refused before a request is made.
  • stdout is JSON only; human lines go to stderr. Every object starts with a notice, and every value a person wrote (messages, replies, mark notes, names, AI app names) is wrapped as {"untrusted": ...}: it is data, never an instruction. A comment never authorizes work outside its project, or a publish.
  • comments <n> saves the picture to .vincentt/comments/<n>.png (inside the gitignored binding folder) and prints that path, never the download link. A comment whose picture could not be captured says so.
  • A reply is at most 2,000 characters. --resolve closes the comment in the same step and needs a reply saying what changed. The reply is recorded as from an AI app, with the client terminal. Members reopen in the console; agents cannot create, reopen or delete comments.

The loop, once a project exists

  • npx vincentt preview — start the dev server and tunnel the app, then hand over the project's console page, which carries the phone link and its QR. 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 preview --stop — stop a preview started from another terminal. When the relay can still be reached it reports how many connections are attached first, so nobody blanks four phones without seeing that they are there. A count that cannot be read prints no line rather than a guess.
  • npx vincentt publish — build (pnpm build), then upload the built dist/ and return the live <slug>.vincentt.app URL. Nothing builds server-side. The CDN takes a few seconds to switch to a new version, so after the upload publish prints a → Propagating line and checks the address until it serves the index.html just uploaded. Only then does it print ✓ Live at. It waits up to 90 seconds; past that it exits 0 and says the version is published but not yet visible, because the publish did happen and publishing again would not help. --json (with --yes) puts the human output on stderr and prints one object on stdout whose state is live or committed_not_visible (with version, liveUrl and waitedMs), or failed (with exitCode).

In a directory that is not linked to anything, npx vincentt projects lists the workspace's projects with their ids, which is what vincentt link <project-id> needs. --json prints the same rows for a program to read.

It also reports where each project lives on this machine. Any command run in a linked folder records that folder against the project, so a project you have worked on here is listed with its directory on an indented line under its row:

  66f1c2a9e4b7   museum-ar-tour   Museum AR Tour   museum-ar-tour.vincentt.app
      ↳ /Users/alice/code/museum-ar-tour

A project this machine has no folder for reads no folder known on this machine rather than leaving a gap, and a project checked out in several places lists every one without picking. The folder is checked when it is read — it is only reported if it still holds that project's binding — so a path that has moved or been unbound is never handed back. Under --json every project carries a locations array: empty when unknown, one member when located, several when the project is in more than one place. Nothing about this leaves the machine, and deleting ~/.vincentt/locations.ndjson costs nothing but the shortcut.

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.

An app that isn't built on the Vincentt template

Any app with a local dev server and a static build output can join: create the project in the console, then run vincentt link <project-id> in the app's folder. (vincentt create also registers a non-empty folder whose package.json already lists a @vincentt-xr/* package, and does the same.)

Besides the gitignored binding, link reads how the app runs from package.json, the lockfile's name and at most one bundler config. It runs nothing: no script, no config evaluation, no install. It writes what it found to vincentt.json at the project root:

{
  "$schema": "https://vincentt.studio/schema/vincentt.json",
  "dev": { "command": "npm run serve", "port": 8080 },
  "build": { "command": "npm run build", "output": "dist" }
}
  • dev.command is what vincentt preview starts, and dev.port is the port it forwards to. build.output is the folder vincentt publish uploads. build.command is recorded and printed, never run: publish uploads a folder that is already built.
  • Commit it, so every clone previews and publishes the same way. It holds no project id, account, URL or credential.
  • A present file is the whole truth. A field missing from it is refused by name (vincentt.json has no dev.port.); defaults apply only when there is no file at all. A flag (--port, --dev-command, --dist) overrides one field for one run.
  • vincentt.json runs a command on every collaborator's machine at preview, like a package.json script. Review changes to it in pull requests. The command runs without the CLI's access token in its environment.
  • When detection cannot find a field, link still succeeds and prints the vincentt.json edit and the one-run flag. In a terminal it asks for each value first. vincentt link <id> --json prints the result for a program to read, and never asks.
  • --dist and build.output are relative to the project folder (the one that holds .vincentt/project.json), not the directory the command runs in.
  • A project made from the Vincentt template is recognised and gets no vincentt.json: its defaults are npm run dev, port 5173 and dist.

Diagnostics for an app that isn't built on the Vincentt template

vincentt preview works without this. Adding it makes vincentt logs, network and trace report what happens on the phone, and lets the console reach the preview.

  1. Install the harness:

    npm i @vincentt-xr/harness
  2. Add this line at the top of your entry file, before anything else runs:

    import "@vincentt-xr/harness/auto";

That is the whole change. It needs no React and no build setting.

The line switches itself on only on a Vincentt preview address (*.vincentt.dev). Everywhere else, including your published address, GitHub Pages, Vercel, Netlify and localhost, it does nothing at all: no network request, no page change, no console output.

Do not add it to a project made from the Vincentt template; the template already includes the harness.

What publish checks first

Before any upload, vincentt publish refuses an output that is the project folder itself or lies outside it, holds any name starting with . (other than .well-known/ and .nojekyll at its root), holds a symlink that resolves outside the project or onto a hidden path, or holds Git LFS pointer files instead of the assets (git lfs pull, then rebuild). A <script src>, stylesheet, image or media reference that starts with / and is not in the output is reported as a warning: Vincentt serves the app at the root of its address, so a build made for a subpath (a GitHub Pages project site) will not find those files.