CLI

The InstaFix 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.

InstaFix isn't published to the npm registry — that's a deliberate choice, so npx @instafix/cli won't resolve. Run it straight from this repo's cli-dist branch instead:

npx github:gnoopy/instafix#cli-dist --help

The command matters. Always run npx github:gnoopy/instafix#cli-dist <command> — spelled out in full, every time. There is no instafix package on npm to shorten it to.

init — interactive setup

npx github:gnoopy/instafix#cli-dist init

init walks you through up to four confirmations:

1. Sync Prisma models — if a schema is found (see schema detection), it offers to add the InstaFixFeedback and InstaFixAnnotation models.
2. Push the schema — if a schema was found, it offers to run npx prisma db push for you right away, streaming Prisma's own output (and any confirmation it asks for) straight to your terminal.
3. Generate the API route — offers to create a Next.js App Router route that serves the widget. The file goes to app/api/instafix/route.ts, or src/app/api/instafix/route.ts when your project uses a src/ layout. An existing route is never overwritten.
   • A schema was found: generates a route against @instafix/adapter-prisma.
   • No schema was found: asks which backend to use instead — SQLite (@instafix/adapter-sqlite, zero external services) or skip and wire storage yourself. init no longer assumes Prisma when there's no Prisma schema to sync against.
4. Generate the widget component — offers to create a "use client" component at components/instafix-widget.tsx (or src/components/... with a src/ layout) that calls initInstaFix() for you, using your package.json name as the projectName. An existing component is never overwritten.

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

• the @instafix/adapter-prisma package (npm install github:gnoopy/instafix#adapter-prisma-dist)
• a Prisma client exported from @/lib/prisma

The SQLite-flavored route only needs @instafix/adapter-sqlite installed (npm install github:gnoopy/instafix#adapter-sqlite-dist) — no client to wire up, no schema to push; see the SQLite adapter.

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.

Whatever wasn't done automatically — declined, or no schema/route detected — is listed under a Next steps note at the end, so nothing is silently skipped.

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 github:gnoopy/instafix#cli-dist sync
npx github:gnoopy/instafix#cli-dist sync --schema prisma/schema.prisma

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

• creates the two models if they are missing,
• adds any missing fields and @@index blocks,
• rewrites InstaFix fields whose type or attributes drifted from the expected shape,
• never touches fields you added yourself.

When something changed, it reminds you to run npx prisma db push. 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. A clean git diff makes the changes easy to review.

status — project health report

npx github:gnoopy/instafix#cli-dist status
npx github:gnoopy/instafix#cli-dist 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 github:gnoopy/instafix#cli-dist doctor --url http://localhost:3000 --endpoint /api/instafix

doctor sends one GET request to your running server and tells you whether a InstaFix handler answered (10-second timeout). Pass both flags to run it non-interactively — any flag you omit becomes a prompt.

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 InstaFix 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