@unbase-app/cli
v0.6.2
Published
Adds Unbase to an Astro, Vite + React or Next.js site, checks it, takes it out again, and renames, duplicates and deletes its pages: unbase init, doctor, uninstall and page.
Maintainers
Readme
@unbase-app/cli
Adds Unbase to an Astro, Vite + React or Next.js site, checks it, and takes it out again.
npx @unbase-app/cli init # the framework's package, its line in its config, comment-modus.json
npx @unbase-app/cli doctor # per feature: on, or what is missing, where, and how to fix it
npx @unbase-app/cli uninstall # all of it out again; the built pages compared before and after
npx @unbase-app/cli page … # rename, duplicate or delete a page, as Unbase's editor doesAlways with the package's name: the unscoped unbase on npm is another product's package, so a
bare npx @unbase-app/cli outside a site that has this CLI installed would fetch that one.
Unbase works on a connected site without any of this: the canvas, comments on the canvas,
publishing, and visual editing (on Astro, nothing installed). What has to live in the site's own
code is what this adds: comments on the live site (?comment), page management (draft pages
kept off Live, page and site settings), and analytics (Unbase's beacon, a pageview from every page
of a production build, no cookies). The packages change how the site is edited and built, never
how it renders, but for the beacon's script, which renders nothing. The CLI itself never calls
Unbase.
Astro, Vite + React with React Router as a library (what Lovable makes: Vite + React, below),
and Next.js; each framework's own steps are in agents/<framework>.md. Node 18.17 or newer for the
CLI (comment-modus itself needs 22.12). Until 03-11-2026 this was @unbase-app/cli; init moves a
site installed with it across (Moving from before 03-11).
For a coding agent
Add Unbase to this site.
1. Run `npx @unbase-app/cli init --yes` and keep its changes.
2. Read node_modules/@unbase-app/cli/AGENTS.md and do the steps it leaves to you.
3. Don't move or rewrite the site's content. Unbase edits text where it is written.
4. Run `npx @unbase-app/cli doctor` until it passes. Commit on a new branch and push it.AGENTS.md is in the package, so the steps are pinned by the site's lockfile. It points to
the framework's own file, agents/astro.md or
agents/vite-react.md, which init names.
unbase init
| Flag | |
|---|---|
| --comments / --no-comments | Comments on the live site, with ?comment (@unbase-app/layer, inside @unbase-app/astro). Default: in, or as the site has it when Unbase is in it already |
| --project <id or slug> | Link comment mode and analytics to an Unbase project now (see Linking) |
| --pointer[=AGENTS.md\|CLAUDE.md] / --no-pointer | One line in the site's AGENTS.md (or CLAUDE.md) pointing its agent at this package's AGENTS.md. Default: no |
| --no-install | Write package.json only; install yourself |
| --tarballs <dir> | Install the packages from npm pack tarballs in <dir>, for testing a release before it is on npm |
| --yes | The default for every choice not given |
| --json, --dir <path> | Output for programs; the site's folder (default: here) |
It adds, with the site's own package manager (npm, pnpm or yarn, from its lockfile), at these versions:
| Package | Version | |
|---|---|---|
| @unbase-app/astro | 0.5.0 | Unbase in an Astro site, one integration: comment mode (@unbase-app/layer 2.0.0: comments on the live site; it writes the content schemas Unbase reads, and its page list and content map reach a host adapter's copy of the output too), the draft-pages kit (@unbase-app/pages 0.5.0: draft pages kept out of production builds, and the redirects a moved page leaves applied) and the analytics beacon (@unbase-app/analytics 0.1.0) |
| @unbase-app/cli | this one | devDependency: AGENTS.md and doctor, pinned |
In astro.config, found and changed through its syntax tree, never by text substitution:
import unbase from "@unbase-app/astro";
import commentModusConfig from "./comment-modus.json";
// …
integrations: [
// …the site's own
unbase({ project: commentModusConfig.project, layerUrl: "https://layer.unbase.app/v1/loader.js", edit: true }),
],unbase() adds comment mode and the kit after every other integration itself, so the kit runs last
wherever the line stands. Its options are comment mode's own; --no-comments writes
unbase({ comments: false }), and init --comments later turns it on in the same line.
A config it cannot change with certainty (CommonJS, no export default, integrations that is not
an array literal, a spread that may hold it) stops the run with the file named and nothing changed.
A package that is already there at an older version is moved up to the pinned one, so running
init again is also how a site updates; a newer one is kept and reported, never moved down. A
second run changes nothing. It touches no content.
Vite + React
One package, @unbase-app/vite (a devDependency, beside vite), at 0.3.0: the draft-pages kit, the analytics beacon and
comment mode's loader in one Vite plugin. In vite.config, through its syntax tree (Lovable's
defineConfig(({ mode }) => ({ … })) and plugins: [ … ].filter(Boolean) included):
import { unbase } from "@unbase-app/vite";
// …
plugins: [react(), mode === "development" && componentTagger(), unbase()].filter(Boolean),--no-comments writes unbase({ comments: false }); init --comments later takes that option
out again. A config with the kit's own Vite plugin (unbasePages() from
@jens4m/unbase-pages/vite) gets unbase() in its place. The plugin reads comment-modus.json
itself, so the config does not import it. A Vite app keeps its site settings in index.html, which
Unbase reads and writes as it is; it has no page settings, so nothing is written for them.
Next.js
On a Next.js site init adds @unbase-app/next (0.3.0) and wraps the config next.config hands Next.js in
withUnbase(…) (through its syntax tree; a CommonJS config gets the require), writes
comment-modus.json, and on a Next.js from 15.3 to 16.2 imports the comments' loader in
instrumentation-client.ts (from 16.3 withUnbase injects it). doctor builds with next build
into the site's own .next and reads it; page settings need nothing installed (each page's
export const metadata), so it lists which pages Unbase can set and why not the others.
uninstall takes it all out and compares the prerendered pages, with Next.js's scripts and hashed
asset names left out. The steps: agents/next.md.
Analytics
The beacon comes with the framework's package, on by default (@unbase-app/analytics): every page
of a production build sends a pageview to Unbase once the site is linked, never in a dev server.
analytics: false in the package's call (unbase({ … }), withUnbase(nextConfig, { … })) leaves
it out; init never writes that, and keeps it when a site has it.
What init adds for it is the collector's origin, https://unbase.app, in connect-src wherever
the site sets a Content-Security-Policy it can edit safely: vercel.json's headers and
public/_headers (Netlify, Cloudflare Pages), each value changed in place and the rest of the file
as it was; with no connect-src, one made of default-src's sources and the origin. A CSP set
anywhere else (next.config's headers(), a middleware, a <meta http-equiv>, netlify.toml,
Astro's csp option) is named in next and csp.elsewhere, never edited. uninstall takes the
origin out of the two files again, to the letter. The reading and the editing are Unbase's own
(lib/readers.mjs, csp), the same code read_install uses for its Analytics row.
On Astro and Vite the package reads comment-modus.json itself, so --no-comments still writes
it for analytics, and --project links analytics alone. On Next.js the beacon comes with the
comments' client module: one link for both, and --no-comments leaves both out.
Linking
comment mode and analytics need the site's Unbase project, which a site added before Unbase knows it
does not have yet. So init writes comment-modus.json with "project": null, and the config only
turns comment mode (and analytics) on once that file names the project: until then the site builds
and renders as before.
Unbase fills the value in when the site is connected (one JSON value, never a change to the
config), or init --project <id> does. comment-modus.json is the same file comment-modus's own
CLI reads.
A config that sets comment mode up itself, with its own project (a site that had comment mode
before init existed), keeps it: init --project with that same project changes nothing there and
writes no comment-modus.json; another project is refused, to be changed in the config by a person.
Moving from before 03-11
A site installed before 03-11-2026 has the pair, @jens4m/comment-modus and @jens4m/unbase-pages
with commentModus() and unbasePages() in its config, and the CLI as @unbase-app/cli. init
moves it across, and it is how Unbase's Update does it:
@unbase-app/astroand@unbase-app/cliin;@jens4m/unbase-pagesand@unbase-app/cliout (removed, withreplacedBy, in--json): written topackage.jsontogether and installed in one run, so theunbasebin both CLIs have is the new one's. A failed install putspackage.jsonback, and nothing else has changed yet.unbase()takescommentModus()'s place with its options as they are (a site's ownproject,titles,language…); thecommentModusConfig.project ? … : nullinit wrote around it goes, sinceunbase()waits for the project itself.unbasePages()and its import go.- Comment mode's own package goes too, under either name (
@unbase-app/layer, or@jens4m/comment-modusbefore 2.0), unless the site uses it for itself: a name its config still imports from it, the package named in its code or a workflow, or the layer's CLI in a script. The layer then stays, moved to the version@unbase-app/astrobrings, so there is one;@jens4m/comment-modusstays as it is, as the layer has no release under that name. Its CLI alone keeps neither: the layer answers tocomment-modustoo. - The pointer line moves to
node_modules/@unbase-app/cli/AGENTS.md. - With
--yes, a site keeps its choice of comments. A second run changes nothing.
doctor passes on a site from before as it is, and says the move is there (moved, info).
unbase doctor
Builds the site once (production, into a folder of its own), then reads it with Unbase's own
readers, the code the Edge Functions run, bundled into this package. Per feature it gives a state
and per check what is missing, the file, and the step in agents/astro.md that fixes it.
| Check state | |
|---|---|
| ok | Works |
| missing | The site has to change. Fails the run |
| waiting | Outside this repository: Unbase linking the project, or a package release. Named, does not fail the run |
| info | Worth knowing |
| skipped | Not checked (--no-build, or a build that failed) |
Features: Visual editing (Astro, the site builds), Comments on the site (the package, its
line, the link, the markers, the loader), Page management (the kit, the drafts in
unbase.pages.json, the kit running in a production build, the content schemas, the route files
and the site settings and that the layout reads them), Analytics (the package at a version that
brings it, not analytics: false, the link, before Next.js 16.3 the client module's import, and the
CSP of vercel.json and public/_headers allowing https://unbase.app; a CSP set elsewhere is
named as info). --no-build skips the build and what needs it.
The markers are comment mode's data-c: a pin on the live site takes its title and source file
from them, so with comments they belong in the production build. A site without comment mode, or
whose unbase() says componentMarker: "preview" (comment-modus 1.9.0: markers in the dev
server and previews only) or false, must have none there; doctor fails when it does, and names
an older comment-modus that ignores "preview".
unbase uninstall
Refuses while unbase.pages.json holds a draft, and lists them: without the kit a draft is built
and goes live, so each is published or deleted in Unbase first. It refuses too while the file
sends old addresses on (redirects, left by renaming or deleting a live page), and lists them:
only the package applies them, so they go into the site's own redirects first. Then it builds the site, removes
the packages, their lines in astro.config, comment-modus.json, unbase.pages.json,
src/content/.schemas/, the collector in the CSP of vercel.json and public/_headers, and the
pointer line, builds again, and compares every page's HTML. Taken out first: comment mode's markers
and loader, the analytics beacon, and what differs between any two builds (asset
hashes, Astro's ids, white space, attribute order). When pages still differ it builds the after
state once more, and what differs between those two builds (an id a component makes at random on
every render) is noise, not a change. "No differences in the built pages" is the pass. --yes without
a terminal; --no-build skips the comparison; --no-install writes package.json only.
The route files, the settings file and the layout's reads stay: they are the site's own code.
unbase page
Makes, renames, moves, duplicates and deletes a page by the kit's own rule (planPage in
@unbase-app/pages's core, bundled here), so the files change exactly as they do when Unbase's
editor does it: the same files always give the same changes. It writes them in the working tree
and commits nothing; review them with git diff and commit them yourself. A page's name and its
address are apart: rename changes the name, move the address.
npx @unbase-app/cli page create /prijzen --name Prijzen
npx @unbase-app/cli page rename /funding --name Financiering
npx @unbase-app/cli page move /funding /financiering
npx @unbase-app/cli page duplicate /pricing /pricing-2027
npx @unbase-app/cli page delete /old-offer --redirect /pricing
npx @unbase-app/cli page list| Command | |
|---|---|
| page create <address> [--name <name>] | A new page in the site's layout, with a heading of its name, made the way the site makes its pages (a file on Astro and Next.js, a route and its file on React Router, a file from the home page's shell on plain HTML); a draft where the kit is installed. The name defaults to the address's last part in words |
| page rename <path> --name <name> | Its name in Unbase only (unbase.pages.json); the address stays |
| page move <from> <to> [--not-live] | A new address: the page's files move (on Next.js its folder, on React Router the route's path, on plain HTML the file), every link to it or below it in code and content follows (code samples in text are left alone), its route file's pad too, and the pages under it come along |
| page rename <from> <to> [--name <name>] [--not-live] | Both at once, as before move existed |
| page duplicate <path> [<to>] [--name <name>] | A copy, by default at the first free <path>-copy, with its own copy of what only the page owns (its modules and content); a draft where the kit is installed. Named "… (copy)" when the original has a name |
| page delete <path> [--redirect <to> \| --not-found] [--not-live] | Its file and what only it owns; shared parts stay. The links to it are listed, not changed. Visitors to the old address go to the page above it, --redirect's page, or with --not-found nowhere |
| page list [--not-live] | Per page: whether it can be renamed, duplicated and deleted here, and if not, why |
Every one takes --dry-run (print the changes, write nothing), --json and --dir.
Live pages. A page counts as live unless --not-live says it was never on the live site. A
live page renamed or deleted leaves a redirect in unbase.pages.json (old address → new), which
the framework's package applies at build from @unbase-app/astro 0.3.0, @unbase-app/vite 0.3.0
and @unbase-app/next 0.3.0 on (@unbase-app/pages 0.4.0). On a site with an older one, or none,
a live rename or delete is refused (no_redirects) instead of breaking the old address: run
unbase init to update, or pass --not-live for a page that never was live.
Refusals exit 1 with the reason and what it means (--json: reason, detail, message):
| Reason | |
|---|---|
| home | Home can be duplicated, not renamed or deleted |
| nested | Delete: pages are under it; delete those first |
| taken | The new address is a page already, or the site's own redirects send it on |
| address | Not an address the page can have (plain segments, not under itself), or --redirect is not a page |
| no_redirects | A live page leaves a redirect, and this site's build does not apply them (above) |
| content_bound | Duplicate: its content is a collection of its own, and a copy needs code the kit does not write. Unbase's Operator can do it |
| content_unregistered | It reads content by a name no content file goes by |
| template | The page is made by a dynamic route: change it where its data is |
| unparsed | The kit cannot trace the page's route to its file |
| missing | The code makes no page at this address |
| same | Nothing to change |
| invalid | unbase.pages.json is not valid |
| framework | Not Astro, Next.js or Vite + React Router |
For programs
- Never asks without a terminal. A choice without its flag is an error (exit 2) naming the
flags;
--jsonnever asks. --jsonon every command.init:packages(name, the pinnedversion, dev, andaction:added,updatedwithfromandto, orkept, with anotewhen the one there is newer) andfiles(file,created,changedorremoved, and the changes; the lockfile too when the package manager ran);analytics(on, unless the config saysanalytics: false) andcsp(filesit allowed the collector in,invalidones it could not read, andelsewhere: each{ file, why }that may set a CSP it does not edit).doctor:features, each withstate(on,off,waiting,not-installed) andchecks(id,state,message, and for amissingorwaitingcheckmissing,file,step).uninstall:files(every file it touched, the lockfile included),packages,comparison(pages,differences,secondBuild), orrefused: "drafts"withdrafts, orrefused: "redirects"withredirects.page:files(eachpathandaction:created,changed,movedorcopiedwithfrom, ordeleted),links(files whose links it rewrote),unlinked(files that still name the old address),redirects(what changed inunbase.pages.json: source → destination,nullfor one that went),moves(the addresses),dryRun; refused:reason,detail,message.page list:pages, each withrename,duplicateanddeleteas{ ok }or{ ok: false, reason }, andredirects(whether the site's build applies them). An error:{ ok: false, exitCode: 2, error: { code, message, file? } }.- Exit codes:
0passed,1failed (doctor found something missing; uninstall refused or found a difference; a page action refused),2could not run (usage, no Astro site, a config it cannot edit safely, an install that failed). - No login, no project, no network beyond the package manager's install: it never calls Unbase, and the versions are pinned.
Developing
Part of the kit (kit/ in Unbase's repository; see its README): npm test there runs every
package's tests. lib/readers.mjs is generated from the Edge Functions' readers (detect.ts,
settings.ts, pages.ts, the kit's core), which live in Unbase's repository: after changing one of
them, node kit/cli/scripts/readers.mjs; the tests fail there while it is out of date. In the kit
on its own the file ships as it was generated.
MIT licence.
