CLI commands

Core commands

The CLI does more than scaffold now, so it deserves its own route instead of a short appendix.

npx clivly init          # scaffold config, routes and env placeholders
npx clivly login         # pair this machine, write credentials to your env file
npx clivly status        # check your setup, step by step (read-only)
npx clivly add widget    # scaffold the chat-session route only
npx clivly push-schema   # push schema, custom objects and mappings, without deploying
npx clivly dev           # tunnel localhost so remote sync can reach you
npx clivly --version     # print the installed clivly version

# Every command accepts --help, which describes without acting.
npx clivly init --help

• init scaffolds three files — clivly.config.ts (yours to edit), the tick route and the auth-verify route (both Clivly-owned, --force to overwrite) — plus env placeholders, and can hand straight into login.
• init generates a config for Drizzle only. Prisma and Kysely projects hand-write a fetchPage source instead.
• login writes to your framework's env file: .env.local on Next.js, .dev.vars on Cloudflare Workers, .env elsewhere. On Workers this is not cosmetic — wrangler reads .dev.vars and nothing else.
• dev opens a cloudflared tunnel so remote sync can hit localhost during development. It needs cloudflared on your PATH. The tunnel targets your framework's usual dev port — 5173 for Vite-based frameworks, 3000 for Next.js and Nuxt — and warns when nothing is listening there; --port overrides it.
• Vite-based apps need server: { allowedHosts: [".trycloudflare.com"] } in their Vite config, or every tunnelled sync fails 403 before reaching the tick route. dev prints this when it applies. Next.js is unaffected.
• If registration fails, the warning names the cause — an invalid key, a backend without the endpoint enabled, an HTTP status Clivly returned, or a real network failure. Outbound sync is unaffected either way.
• push-schema sends table and column names without a deployment — never row data — and also creates the custom object types your config declares plus the mappings that make them receive rows.
• Mappings are what make a sync store anything. A workspace with no mappings rejects a push outright, naming what is missing; a workspace mapped for some entities but not others accepts the push and drops those rows, and the SDK warns once per entity. clivly status reports both as Entities mapped in Clivly.
• push-schema exits 1 if Clivly refuses your config — most often because an entity would overwrite a mapping edited in the dashboard — so it is safe to run in CI as a schema gate.
• add widget scaffolds only the chat-session route — idempotent, and it creates no widget record (that lives in the dashboard).

Telling init where things live

init detects your framework, ORM and auth library, then probes the conventional locations for your schema, database instance and auth instance. When it finds your better-auth instance it prints Auth: better-auth (wired) and imports it directly into the auth-verify route.

Pass a flag only when the probe cannot see something — most often because it lives in a sibling workspace package.

npx clivly init --schema ./src/lib/server/schema.ts
npx clivly init --db-import '@acme/database#database'
npx clivly init --auth-import '$lib/server/auth'
npx clivly init --contact-table patients --company-table practices

• --auth-import and --db-import accept an alias or subpath import ($lib/server/auth, @/lib/auth, #auth), a package name, or a project-relative path (src/lib/server/auth). The first two are emitted unchanged because they already resolve; a path is rebased to the route file's depth.
• Both accept @acme/database#database to name the export when the module does not use the conventional name.
• --contact-table and --company-table take either the SQL table name or the name it is exported under in your schema module. Use them when a schema has more than one plausible people table, or to override the naming heuristics.
• If the auth probe finds nothing, init says so and repeats --auth-import rather than scaffolding an import that will not resolve.

Use the right diagnostic command

Reach for status first. The other three are kept because older output and docs recommended them.

npx clivly status   # the whole guided ladder — prefer this

# Deprecated aliases. Each runs part of the same ladder.
npx clivly ping     # credential + reachability
npx clivly connect  # the above, plus config and trigger URL
npx clivly doctor   # config, setup checks and edge safety

• status runs the whole ladder and tells you which step you are on: credential → Clivly reachable → config loads → config is edge-safe → setup checks → sync trigger URL.
• ping, connect and doctor are deprecated aliases, each running part of that same ladder. They still work.
• In code, await clivly.doctor() returns { ok, checks } — API key, entities, sources, concept coverage, cursor/id columns, sample fetch, mapping dry-run, custom-object slugs, heartbeat, namespace reachability.
• Checks can come back warn: true — a working setup carrying a risk worth stating, such as paging on a column that never changes on edit. Warnings do not fail the report.