citelens-setup

Citelens setup & launch

Get the self-hosted Citelens dashboard running from a clone. Citelens is a Next.js + SQLite app — no external services required to start.

Steps

Run from the Citelens repo root. Check each step's output before moving on.

1. Dependencies — if node_modules is missing:

   npm install
   

2. Environment — if there is no .env, create it from the template:

   cp .env.example .env
   

   Then read .env.example to see the supported keys. Citelens runs with no keys (deterministic mock engine, full loop works offline). For real data, set at least GEMINI_API_KEY (free from https://aistudio.google.com/apikey). Other engines activate when their key is present: ANTHROPIC_API_KEY, OPENAI_API_KEY, PERPLEXITY_API_KEY. If the user provided a key, write it into .env with Edit — never echo a full key back.

3. Database — create the local SQLite database:

   npm run db:migrate
   

4. Launch — start the app:

   npm run dev          # http://localhost:3000
   

   For a production-style boot (build + migrate + start) use the one-command launcher instead:

   node bin/citelens.mjs
   

After launch

Tell the user to open http://localhost:3000, create a project (brand, domain, competitors, topics), and run it. Citelens auto-generates buyer-intent prompts, runs them across the engines, and shows visibility, share of voice, sentiment, cited sources, and the action loop.

No-key browser mode (optional)

If the user wants real AI answers without API keys or spend, set CITELENS_BROWSER=1 — Citelens drives the real web UIs (Perplexity and Google AI Overview need no login; ChatGPT and Gemini need a one-time login via the in-app Browser mode). It is experimental, slower, and subject to each site's terms; the API path always works without it.

Quick check without the dashboard

If the user just wants a one-off visibility number rather than the full app, use the /citelens:check skill — it runs the same GEO pipeline straight in the terminal.