Cluebase CLI

This package owns the Cluebase setup CLI.

The Cluebase product repository keeps SDKs, shared schemas, and API contracts. Tool implementation lives here so client repositories do not receive tool source code.

Commands

The public npm package is @genn-inc/cluebase-cli. The binary exposed by that package is cluebase-ai, but first-run setup should not assume a global cluebase-ai install. Use npx -y @genn-inc/cluebase-cli <command> unless .cluebase/setup-manifest.json explicitly provides a different invocation.

npx -y @genn-inc/cluebase-cli setup --cluebase-api-key <ak_dev_or_prod_key> --cluebase-api-base-url <cluebase-api-base-url> --project-key <pk_dev_or_prod_key>
npx -y @genn-inc/cluebase-cli setup-check --framework fastapi --backend-root-path backend --repo . --require-sdk-lifecycle
npx -y @genn-inc/cluebase-cli setup-doctor --repo .

npx -y @genn-inc/cluebase-cli setup performs the machine-owned preparation that is needed before using the single AI setup prompt shown in the Cluebase setup screen:

• detects frontend services (React/Vite, Next.js, Vue, Angular, SvelteKit, Nuxt) and backend services (Python: FastAPI/Django/Flask and other WSGI/ASGI apps; Node: Express/NestJS/Fastify/Koa) from dependency manifests and framework import signals — language, framework, and service root only
• writes .cluebase/setup-manifest.json
• writes the single .cluebase/.env reference file in standard flat dotenv format when all three Cluebase values are supplied; existing .env* files are never modified

A frontend-only project (single-page app plus serverless/static hosting, with no detectable backend) is a supported setup path and continues as a frontend SDK integration rather than being blocked. Setup is blocked only when no frontend or backend service is detected at all.

Route and lifecycle-boundary inventory is not enumerated by a per-framework parser. The AI setup prompt reads the customer codebase and decides the actual integration points, so unsupported frameworks and unknown routes can be handled from the repository's real configuration instead of a generated framework-specific handoff.

The setup prompt uses an official Cluebase SDK for the target runtime. If no official SDK can be resolved, stop and report that the SDK must be published or made available; do not replace it with a customer-owned HTTP client or proxy route. The Cluebase environment (dev/prod) is derived from the project key prefix (pk_dev_ vs pk_prod_).

npx -y @genn-inc/cluebase-cli setup-check mechanically verifies the setup manifest, obvious secret leaks, and SDK lifecycle presence when requested. With --require-sdk-lifecycle, a passing result is still static only; dependency installation, SDK imports in the target environments, app startup, and event delivery remain required before setup can be called complete.

npx -y @genn-inc/cluebase-cli setup-doctor --repo . checks API connectivity and the customer-scoped runtime verification required after user-operated lifecycle verification. Its preflight verifies three setup hops:

1. frontend SDK to Cluebase /api/v1/ingest/browser-tokens (short-lived token issuance — the frontend SDK calls the Cluebase backend directly using the public project key and request Origin, no customer-backend proxy in between).
2. customer frontend to Cluebase canonical browser observation batch ingest with the short-lived token.
3. customer backend to Cluebase /api/v1/ingest/backend (server-side ingest with CLUEBASE_API_KEY).

It also scans the customer backend for /api/v1/cluebase/* proxy routes and emits a blocking error requiring removal (customer_backend_cluebase_route_forbidden). Setup-doctor does not replace real login, organization, or logout flows. Start the local customer frontend/backend and perform a normal product flow yourself. Then rerun setup-doctor; it reads only a safe summary of the target project's recent committed auto-capture events. It does not claim that those events were caused by the current doctor run and does not expose raw events or Cluebase infrastructure details. If no event exists, doctor remains pending and tells you to operate the product and retry.

npx -y @genn-inc/cluebase-cli setup reads the Cluebase API base URL, project key, and API key from setup screen flags, detects local services, writes .cluebase/setup-manifest.json, and writes the same values to .cluebase/.env. The file is a machine-owned reference artifact, is created with mode 0600, and is automatically added to .gitignore. It is not loaded automatically by a customer application; after implementation, setup-doctor reports the target runtime environment variables that the user must configure.

Required Environment

• CLUEBASE_API_BASE_URL: Cluebase API base URL shown by the setup screen. The backend SDK derives /api/v1/ingest/backend from this value.
• CLUEBASE_PROJECT_KEY: Cluebase setup screen issues this value.
• CLUEBASE_API_KEY: Cluebase setup screen issues this value.

.cluebase/.env stores these three ordinary dotenv assignments:

CLUEBASE_API_BASE_URL="https://api.example.com"
CLUEBASE_PROJECT_KEY="pk_dev_example"
CLUEBASE_API_KEY="ak_dev_example"

The file is a reference source. The customer application uses the variable names required by its actual runtime; frontend frameworks add their public prefix where needed. CLUEBASE_API_KEY must never be copied into browser code or a public frontend variable.

Boundaries

• The tool may read allowed source paths in the client repository.
• The tool must not read .env, secrets, logs, dumps, build output, or vendor directories.
• Raw source code, raw SQL, bind values, function names, class names, file paths, and import graphs must not be sent to Cluebase.