CLI

The SitePing CLI automates project setup and health checks. It ships as a single self-contained binary with zero runtime dependencies and requires Node 20 or newer.

npx @siteping/cli --help

The package name matters. Always run npx @siteping/cli <command>. There is no siteping package on npm, so npx siteping only works if @siteping/cli is already installed in your project.

init — interactive setup

npx @siteping/cli init

init walks you through two confirmations:

1. Sync Prisma models — if a schema is found (see schema detection), it offers to add the SitePing models: SitepingFeedback, SitepingAnnotation and SitepingComment (the discussion threads).
2. Generate the API route — offers to create a Next.js App Router route that serves the widget. The file goes to app/api/siteping/route.ts, or src/app/api/siteping/route.ts when your project uses a src/ layout. If both app/ and src/app/ exist, app/ wins — Next.js itself ignores src/app/ then. An existing route — route.ts, .tsx, .js or .jsx — is never overwritten.

The generated route imports two things you need to provide yourself — the CLI installs nothing:

• the @siteping/adapter-prisma package (npm i @siteping/adapter-prisma)
• a Prisma client exported from @/lib/prisma

If your project has no app/ (or src/app/) directory, init exits with an error: it only scaffolds Next.js App Router routes. Other frameworks wire the adapter manually — see Adapters.

init is interactive by design and does nothing in CI (it exits silently without a terminal). For automation, use sync.

sync — non-interactive schema merge

npx @siteping/cli sync
npx @siteping/cli sync --schema prisma/schema.prisma

sync merges the SitePing models into your Prisma schema without prompts, which makes it safe for CI and update scripts. It works at the AST level:

• creates the SitePing models that are missing — in the database schema of the existing SitePing models (their @@schema) when your datasource declares several schemas,
• adds any missing fields and @@index blocks,
• rewrites SitePing fields whose type or attributes drifted from the expected shape — keeping the parts that are yours (@map column names, relation names, a relation's onUpdate, comments); an @ignore counts as drift, since the adapter writes every SitePing column,
• never touches fields you added yourself.

When something changed, it reminds you to run npx prisma db push and npx prisma generate (Prisma 7 no longer generates the client from db push). An existing schema gets SitepingComment and the SitepingFeedback.comments relation this way: apply them before you deploy — see discussion threads with Prisma. Running it twice in a row is a no-op.

Commit before you run it. sync re-prints the whole schema file, so formatting (blank lines after // comments, column alignment) is normalized across your own models too — /// doc comments stay attached to what they document. A clean git diff makes the changes easy to review.

status — project health report

npx @siteping/cli status
npx @siteping/cli status --schema prisma/schema.prisma

status runs four checks and prints a report:

The API route check only knows about the Next.js App Router. If you serve the adapter from Express, Hono, or the Pages Router, that line will read "Not found" even though your setup works.

doctor — live endpoint check

npx @siteping/cli doctor --url http://localhost:3000 --endpoint /api/siteping
npx @siteping/cli doctor --url https://app.example.com --api-key "$SITEPING_API_KEY"

doctor sends one GET request to your running server and tells you whether a SitePing handler answered (10-second timeout). Pass both --url and --endpoint to run it non-interactively — either one you omit becomes a prompt. When the endpoint is configured with an apiKey and GET is not public, pass the key with --api-key; without it, a 401 comes with a hint.

--url is your site's base URL, not the endpoint's: a path in it (a Next.js basePath, for example) goes in front of --endpoint. With --url https://example.com/app --endpoint /api/siteping, doctor requests https://example.com/app/api/siteping.

It checks the HTTP response only — it never reads your schema. For schema verification, use status.

Exit codes

All commands are scriptable. 0 means success, 1 means something needs fixing:

Two caveats for CI pipelines: status exits 0 (with a hint to run sync) when schema fields merely drift, and doctor exits 0 on any 200 response — even one that is not a SitePing handler (it prints a warning instead). Neither is a strict gate.

Schema detection

When you don't pass --schema, the CLI probes three locations in order:

1. prisma/schema.prisma
2. schema.prisma
3. prisma/schema/schema.prisma

A schema file inside a schema/ folder (like prisma/schema/schema.prisma) is treated as part of a multi-file schema, as Prisma does: every .prisma file in that folder and its subfolders counts, except under node_modules and hidden folders. SitePing models are found and updated in whichever file holds them; missing ones are added to the file you pointed at. A folder that holds a package.json is a project root, never a schema folder, even if it is named schema. A multi-file schema folder with any other name isn't detected: the CLI then only sees the file you point it at.