CLI reference

The revyse command-line tool runs on your machine. It sets a project up, connects the directory to your Revyse account, and runs the local agent next to your dev server. Every command prints what it is about to do and asks before writing anything.

revyse init

Sets Revyse up in the app, asking before each step:

1. It shows the data disclosure and asks you to accept it.

2. It proposes the next.config edit that adds withRevyse() as a diff you approve.

3. It writes revyse.config.json and adds .revyse/ to .gitignore.

4. It installs revyse and @revyse/next as dev dependencies at its own version, moving them out of dependencies.

5. It connects the app to Revyse. It asks what to call the project (the name in package.json by default), and the browser opens to sign in, where you create it or pick an existing one. An app already connected is shown its project and keeps it unless you ask for another.

6. It connects what changes from your live site and the dashboard need, so nothing is left to set up on the dashboard:

   • The GitHub repository your git remote names (with several, the one your Vercel project deploys). When Revyse's GitHub App can already see it, it's connected at once, on its default branch. Otherwise your browser opens to install the App (or give it the repository), and init waits until you're back.
   • The Vercel project that deploys the app, for previews: the one vercel link recorded in .vercel/project.json, or one you name. The same way: at once when Revyse's Vercel integration can see it, otherwise after you install it in the browser.

   If the project is connected to another repository than your code's, or Revyse watches another Vercel project than the one the app is linked to, init says so and offers to switch, since changes and previews would otherwise go where nothing deploys. Connecting them is an owner's job, so anyone else gets the link to the project's settings.

7. It sets up your live site. It registers the site's addresses on the project: your Vercel project's production domains and the ones in appOrigins that aren't local, once you confirm them, or ones you type. It moves them out of appOrigins, which is for your dev server, and proposes adding live: { projectKey: "pk_live_…" } to withRevyse() in next.config as a diff you approve. When your app sends a Content Security Policy written in next.config or the middleware, it adds Revyse to script-src and connect-src, as a diff too; a policy built at run time gets the exact lines to add. Registering addresses is an owner's job, so anyone else gets the link to the project's Live site tab instead.

8. On Vercel, it turns on exact locations, so a selection on your live site leads Revyse to the exact line of code. Revyse sets a build token on your Vercel project (REVYSE_BUILD_TOKEN, never shown). init shows two diffs and asks once: it adds locations: true to the live option, and && revyse live upload to your build script. Off Vercel, it links to how to do it yourself.

9. It commits the files it changed, and only those, and pushes them, so your site deploys with Revyse: one question, and a file you'd already changed stays out of the commit. On the branch your site deploys from, it then waits for the live site to serve Revyse, and says when it does. On another branch, it says your site gets Revyse once that's merged.

Decline the disclosure and nothing is written. Run again in an app that's already set up, it skips what's done and finishes the rest. If revyse.config.json runs your tests after every change, it asks once whether to keep doing that, since they slow each change down; no (the default) removes test from scripts and keeps the other checks.

BROWSER=none stops it opening the browser; the link is printed either way.

The fields of revyse.config.json are in the local quickstart.

revyse login

Connects the current directory to a Revyse project, or another one than init chose. The browser opens (the link is printed too); sign in, check the code and pick the project, or create one. The CLI gets a token scoped to that one project, stored in your home directory. Owners can revoke any token from the project's settings.

revyse whoami

Shows the account and project this directory is connected to.

revyse logout

Revokes this directory's token on the server and forgets it locally. It takes effect on the token's next request.

revyse dev

Next.js apps don't need it: withRevyse() starts the local agent inside next dev, and its messages appear in the dev server's output, prefixed [revyse]. revyse dev runs the same agent on its own, for dev servers withRevyse() doesn't wrap or for debugging; if the agent is already running for the project, it says so and exits.

The agent listens on agentPort from revyse.config.json (default 4545) and only accepts the overlay from the origins in appOrigins. Two apps can't share a port: the second dev server says which project holds it, and you set another agentPort in its revyse.config.json. REVYSE_AGENT=off stops next dev from starting the agent. The overlay appears in development builds only.

revyse env pull

Writes the variables of the services your organization has connected in Revyse (for Resend, RESEND_API_KEY and EMAIL_FROM) into .env.local, so the app runs locally as it does on its host. It shows the names and asks first; it writes only into a file git ignores, readable by you only, keeping the file's other lines. Project owners only; each pull is audited by variable name. See connecting services.

revyse live upload

Run after next build on a site built with withRevyse(…, { live: { projectKey, locations: true } }): sends the build's exact locations (each opaque element id, with its file and line) to Revyse for the commit being deployed. Needs REVYSE_BUILD_TOKEN, from the project's Live site tab. If the upload fails, it warns and the deploy goes on. See make changes on your live site.

revyse change plan and revyse change apply

Headless commands the cloud worker runs inside an isolated workspace to plan and apply a change that was requested from the dashboard. You don't normally run them yourself.

Environment variables