eyepup

v0.5.2

Published

8 days ago

Eyepup CLI · know who actually visits your site

0High
0Medium
0Low

domnulzeu

analytics visitor-tracking posthog ai dossiers

Eyepup CLI

Skip the dashboard. Just ask the terminal.

Eyepup writes a verdict on every visitor that hits your site — what they wanted, what blocked them, the one fix to ship. The dashboard at eyepup.com is one way to read it. The CLI is the other.

npm install -g eyepup
eyepup login          # opens browser, saves a token
eyepup install        # auto-injects the snippet into your project
eyepup todo           # what to fix this week

If you ship code with Claude Code, Cursor, or GitHub Copilot CLI, the CLI is the surface those agents read from. They can pull dossiers, check recent friction patterns, log changes you shipped, and ask natural-language questions — all without opening a browser.

Install

# Global install (preferred — `eyepup` lands on your PATH)
npm install -g eyepup

# Or one-shot via npx
npx eyepup login

Requires Node ≥ 18.

First-run

eyepup login

Opens eyepup.com/cli-auth in your browser. Sign in (magic link or password), confirm the device, and the CLI receives a token over a one-time loopback callback. The token + your site config land at ~/.eyepuprc.json.

After that:

eyepup install        # auto-injects the snippet into your project
                      # (Next.js app/pages, Nuxt, Astro, Vite, plain HTML)

eyepup status         # confirm events are flowing
eyepup todo           # see what the AI surfaced this week

Once you've shipped a fix, mark it:

eyepup log "Rewrote pricing copy" --paths /pricing
eyepup done 14        # mark friction pattern #14 resolved

The dossier agent reads your changelog when re-evaluating future visitors — your fix shows up in the LLM's reasoning.

Commands

Auth + config

| Command | Description | | --- | --- | | eyepup login | Browser-based auth (recommended). Saves token + site config. | | eyepup logout | Wipe ~/.eyepuprc.json. | | eyepup whoami | Show current config (site, team, dashboard URL). | | eyepup token <epk_live_…> | Manually paste an API token (mint at eyepup.com/integrations). | | eyepup token --clear | Remove the saved token. | | eyepup init | Legacy interactive setup. Prefer login. |

Site setup

| Command | Description | | --- | --- | | eyepup install [--dry-run] [--site <domain>] | Auto-detect your stack (Next.js / Nuxt / Astro / Vite / HTML) and inject the tracking snippet into the right file. --dry-run previews without writing. | | eyepup snippet [site] | Print the snippet for a given site (no auto-inject). |

Read your visitors

| Command | Description | | --- | --- | | eyepup status [site] | Live counts: visitors, sessions, channels, top sources, AI traffic share. | | eyepup tail [site] | Stream new visitors as they arrive (polls every 3s). Cmd-C to stop. | | eyepup hottest [site] | Top 5 high-intent visitors right now. | | eyepup visitors [...] | List recently profiled visitors with their LLM verdict. Flags below. | | eyepup visitor <distinct_id> | Full dossier + recent sessions for one visitor. | | eyepup acquisition [site] [--days 7\|30] | Channel + source breakdown for a site. | | eyepup funnels [site] [--days 7\|30] | AI-generated conversion funnels for a site. |

`eyepup visitors` flags

| Flag | Default | Notes | | --- | --- | --- | | --site <slug> | current config | Filter to one site. | | --limit <n> | 20 | Max rows. | | --sort <key> | newest | newest \| hottest \| buy \| confidence \| sessions \| rage \| oldest. | | --flag <name> | — | high_intent, frustrated, confused, etc. | | --hours <n> | — | Only visitors seen in last N hours. | | --persona <text> | — | Substring match on the LLM's persona label. |

Act on what you find

| Command | Description | | --- | --- | | eyepup todo [--site] [--limit] [--all] | List the friction-pattern To-Do queue (pending first). | | eyepup done <pattern_id> | Mark a friction pattern resolved. Auto-records to the changelog. | | eyepup log <title> [...] | Log a change you shipped. The dossier agent reads it on every re-evaluation. |

`eyepup log` flags

| Flag | Notes | | --- | --- | | --site <site> | Site label (defaults to configured site). | | --paths <list> | Comma-separated affected paths, e.g. /pricing,/about. | | --description <text> | Longer notes the AI should weigh. | | --applied-at <iso> | Override the applied-at timestamp (ISO 8601). |

Ask anything

eyepup ask "why are people bouncing from /pricing?"
eyepup ask "did the rewrite improve conversion?" --site eyepup --days 30

The ask command runs an LLM agent against your dossier population, friction patterns, and recent changelog. Same context the dashboard uses, just answered as prose in your terminal.

| Flag | Default | | --- | --- | | --site <domain> | whole team | | --days <n> | 7 (1–90 valid) |

Use it from an AI agent

The CLI is designed to be called from agentic dev tools. Every command's stdout is structured so an LLM can parse it; non-zero exit codes signal real failures (auth, network, etc.).

Claude Code / Cursor

Mid-conversation, ask the agent things like:

"Run eyepup todo and pick the highest-impact item to work on."
"Pull eyepup visitor <id> for the dossier the user mentioned."
"After I deploy the pricing fix, run eyepup log 'Rewrote pricing copy' --paths /pricing."

The agent calls the CLI, parses output, and decides next steps. No dashboard required.

GitHub Actions

Auto-log shipped changes:

- name: Log to Eyepup
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: |
    npm install -g eyepup
    eyepup token "${{ secrets.EYEPUP_TOKEN }}"
    eyepup log "${{ github.event.head_commit.message }}" \
      --paths "$(git diff --name-only HEAD~1 | paste -sd,)"

The next dossier write for any visitor on an affected path will reason about your change.

Config

Stored at ~/.eyepuprc.json after login:

{
  "site": "yourstartup.com",
  "team_id": "00000000-0000-0000-0000-000000000000",
  "agent_url": "https://eyepup.com/i",
  "dashboard_url": "https://eyepup.com",
  "api_token": "epk_live_…"
}

You can override --site per-command for multi-site teams. The team_id lives on your /sites page in the dashboard.

Privacy + security

Tokens stored in ~/.eyepuprc.json with 0600 permissions (owner-read only).
All API traffic goes through eyepup.com — customer CSPs only need eyepup.com in script-src + connect-src.
Session recording masks all <input> content by default (PII never leaves the browser).
Read-write commands (log, done, token) require an API token. Read-only commands work with just the site config.

License

MIT