@agent-analytics/cli 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Analytics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# agent-analytics
+
+Web analytics your AI agent can read. Drop a JS snippet on your site, query the data via API.
+
+## Quick Start
+
+```bash
+# 1. Get your API key from https://api.agentanalytics.sh (sign in with GitHub)
+
+# 2. Save your key
+npx agent-analytics login --token aak_your_key
+
+# 3. Create a project
+npx agent-analytics create my-site --domain https://mysite.com
+
+# 4. Check your stats
+npx agent-analytics stats my-site
+```
+
+## Commands
+
+```bash
+# Auth
+npx agent-analytics login --token <key>    # Save your API key
+npx agent-analytics whoami                  # Show current account
+
+# Projects
+npx agent-analytics create <name> --domain <url>    # Create a project
+npx agent-analytics projects                        # List your projects
+npx agent-analytics delete <id>                     # Delete a project
+
+# Analytics
+npx agent-analytics stats <name>              # Stats (last 7 days)
+npx agent-analytics stats <name> --days 30    # Stats (last 30 days)
+npx agent-analytics events <name>             # Recent events
+npx agent-analytics properties-received <name>  # Property keys per event
+
+# Security
+npx agent-analytics revoke-key     # Revoke and regenerate API key
+```
+
+## For AI Agents
+
+Set the env var and call the API directly — no CLI needed:
+
+```bash
+export AGENT_ANALYTICS_API_KEY=aak_your_key
+
+# Query stats
+curl "https://api.agentanalytics.sh/stats?project=my-site&days=7" \
+  -H "X-API-Key: $AGENT_ANALYTICS_API_KEY"
+
+# Create a project
+curl -X POST "https://api.agentanalytics.sh/projects" \
+  -H "X-API-Key: $AGENT_ANALYTICS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "new-site", "allowed_origins": "https://mysite.com"}'
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGENT_ANALYTICS_API_KEY` | API key (overrides config file) |
+| `AGENT_ANALYTICS_URL` | Custom API URL (for self-hosted) |
+
+## Config
+
+Stored at `~/.config/agent-analytics/config.json` (file permissions: 600).
+
+## Links
+
+- **Dashboard:** https://api.agentanalytics.sh
+- **Website:** https://agentanalytics.sh
+- **GitHub:** https://github.com/Agent-Analytics
+- **Self-host:** https://github.com/Agent-Analytics/agent-analytics
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+
+/**
+ * agent-analytics CLI
+ * 
+ * Usage:
+ *   npx agent-analytics login --token <key>  — Save your API key
+ *   npx agent-analytics create <name>         — Create a project and get your snippet
+ *   npx agent-analytics projects             — List your projects
+ *   npx agent-analytics stats <name>         — Get stats for a project
+ *   npx agent-analytics events <name>        — Get recent events
+ *   npx agent-analytics properties-received <name> — Show property keys per event
+ *   npx agent-analytics init <name>          — Alias for create
+ *   npx agent-analytics delete <id>          — Delete a project
+ *   npx agent-analytics revoke-key           — Revoke and regenerate API key
+ *   npx agent-analytics delete-account       — Delete your account (opens dashboard)
+ *   npx agent-analytics whoami               — Show current account
+ */
+
+import { AgentAnalyticsAPI } from '../lib/api.mjs';
+import { getApiKey, setApiKey, getBaseUrl, getConfig, saveConfig } from '../lib/config.mjs';
+
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+
+function log(msg = '') { console.log(msg); }
+function success(msg) { log(`${GREEN}✓${RESET} ${msg}`); }
+function warn(msg) { log(`${YELLOW}⚠${RESET} ${msg}`); }
+function error(msg) { log(`${RED}✗${RESET} ${msg}`); process.exit(1); }
+function heading(msg) { log(`\n${BOLD}${msg}${RESET}`); }
+
+function requireKey() {
+  const key = getApiKey();
+  if (!key) {
+    error('Not logged in. Run: npx agent-analytics login');
+  }
+  return new AgentAnalyticsAPI(key, getBaseUrl());
+}
+
+// ==================== COMMANDS ====================
+
+async function cmdLogin(token) {
+  if (!token) {
+    heading('Agent Analytics — Login');
+    log('');
+    log('Pass your API key from the dashboard:');
+    log(`  ${CYAN}npx agent-analytics login --token aak_your_key_here${RESET}`);
+    log('');
+    log('Or set it as an environment variable:');
+    log(`  ${CYAN}export AGENT_ANALYTICS_API_KEY=aak_your_key_here${RESET}`);
+    log('');
+    log(`Get your API key at: ${CYAN}https://app.agentanalytics.sh${RESET}`);
+    log(`${DIM}Sign in with GitHub → your API key is shown once on first signup.${RESET}`);
+    return;
+  }
+
+  // Validate the token works
+  const api = new AgentAnalyticsAPI(token, getBaseUrl());
+  try {
+    const account = await api.getAccount();
+    setApiKey(token);
+    const config = getConfig();
+    config.email = account.email;
+    config.github_login = account.github_login;
+    saveConfig(config);
+
+    success(`Logged in as ${BOLD}${account.github_login || account.email}${RESET}`);
+    log(`${DIM}API key saved to ~/.config/agent-analytics/config.json${RESET}`);
+    log(`\nNext: ${CYAN}npx agent-analytics create my-site${RESET}`);
+  } catch (err) {
+    error(`Invalid API key: ${err.message}`);
+  }
+}
+
+async function cmdCreate(name, domain) {
+  if (!name) error('Usage: npx agent-analytics create <project-name> --domain https://mysite.com');
+  if (!domain) error('Usage: npx agent-analytics create <project-name> --domain https://mysite.com\n\nThe domain is required so we can restrict tracking to your site.');
+
+  const api = requireKey();
+
+  heading(`Creating project: ${name}`);
+
+  try {
+    const data = await api.createProject(name, domain);
+
+    success(data.existing
+      ? `Found existing project for ${BOLD}${domain}${RESET}!\n`
+      : `Project created for ${BOLD}${domain}${RESET}!\n`);
+
+    heading('1. Add this snippet to your site:');
+    log(`${CYAN}${data.snippet}${RESET}\n`);
+
+    heading('2. Your agent queries stats with:');
+    log(`${CYAN}${data.api_example}${RESET}\n`);
+
+    heading('Project token (for the snippet):');
+    log(`${YELLOW}${data.project_token}${RESET}\n`);
+
+  } catch (err) {
+    error(`Failed to create project: ${err.message}`);
+  }
+}
+
+async function cmdProjects() {
+  const api = requireKey();
+
+  try {
+    const data = await api.listProjects();
+    const projects = data.projects;
+
+    if (!projects || projects.length === 0) {
+      log('No projects yet. Create one:');
+      log(`  ${CYAN}npx agent-analytics create my-site${RESET}`);
+      return;
+    }
+
+    heading(`Your Projects (${projects.length})`);
+    log('');
+
+    for (const p of projects) {
+      const created = new Date(p.created_at).toLocaleDateString();
+      log(`  ${BOLD}${p.name}${RESET}  ${DIM}created ${created}${RESET}`);
+      log(`  ${DIM}token:${RESET} ${p.project_token}`);
+      log(`  ${DIM}origins:${RESET} ${p.allowed_origins || '*'}`);
+      log('');
+    }
+  } catch (err) {
+    error(`Failed to list projects: ${err.message}`);
+  }
+}
+
+async function cmdStats(project, days = 7) {
+  if (!project) error('Usage: npx agent-analytics stats <project-name> [--days N]');
+
+  const api = requireKey();
+
+  try {
+    const result = await api.getStats(project, days, { returnHeaders: true });
+    const data = result.data;
+    const headers = result.headers;
+
+    heading(`Stats: ${project} (last ${days} days)`);
+    log('');
+
+    if (data.totals) {
+      log(`  ${BOLD}Total events:${RESET}   ${data.totals.total_events || 0}`);
+      log(`  ${BOLD}Unique users:${RESET}   ${data.totals.unique_users || 0}`);
+    }
+
+    if (data.events && data.events.length > 0) {
+      log('');
+      heading('Events:');
+      for (const e of data.events) {
+        log(`  ${e.event}  ${DIM}→${RESET}  ${BOLD}${e.count}${RESET}  ${DIM}(${e.unique_users} users)${RESET}`);
+      }
+    }
+
+    if (data.daily && data.daily.length > 0) {
+      log('');
+      heading('Daily:');
+      for (const d of data.daily) {
+        const bar = '█'.repeat(Math.min(Math.ceil(d.total_events / 5), 40));
+        log(`  ${d.date}  ${GREEN}${bar}${RESET}  ${d.total_events} events`);
+      }
+    }
+
+    // Monthly usage summary from response headers
+    const monthlyUsage = headers['x-monthly-usage'];
+    if (monthlyUsage) {
+      const events = parseInt(monthlyUsage, 10);
+      const bill = (events / 1000) * 2;
+      const monthlyLimit = headers['x-monthly-limit'];
+      const pct = headers['x-monthly-usage-percent'];
+      log('');
+      if (monthlyLimit && pct) {
+        const capDollars = (parseInt(monthlyLimit, 10) / 1000) * 2;
+        log(`  ${DIM}Monthly usage:${RESET} ${events.toLocaleString()} events ($${bill.toFixed(2)}) — ${pct}% of $${capDollars.toFixed(2)} cap`);
+      } else {
+        log(`  ${DIM}Monthly usage:${RESET} ${events.toLocaleString()} events ($${bill.toFixed(2)})`);
+      }
+    }
+
+    log('');
+  } catch (err) {
+    error(`Failed to get stats: ${err.message}`);
+  }
+}
+
+async function cmdEvents(project, opts = {}) {
+  if (!project) error('Usage: npx agent-analytics events <project-name> [--days N] [--limit N]');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getEvents(project, opts);
+
+    heading(`Events: ${project}`);
+    log('');
+
+    if (!data.events || data.events.length === 0) {
+      log('  No events yet.');
+      return;
+    }
+
+    for (const e of data.events) {
+      const time = new Date(e.timestamp).toLocaleString();
+      log(`  ${DIM}${time}${RESET}  ${BOLD}${e.event}${RESET}  ${DIM}${e.user_id || ''}${RESET}`);
+      if (e.properties) {
+        log(`    ${DIM}${JSON.stringify(e.properties)}${RESET}`);
+      }
+    }
+    log('');
+  } catch (err) {
+    error(`Failed to get events: ${err.message}`);
+  }
+}
+
+async function cmdPropertiesReceived(project, opts = {}) {
+  if (!project) error('Usage: npx agent-analytics properties-received <project-name> [--since DATE] [--sample N]');
+
+  const api = requireKey();
+
+  try {
+    const data = await api.getPropertiesReceived(project, opts);
+
+    heading(`Received Properties: ${project}`);
+    log('');
+
+    if (!data.properties || data.properties.length === 0) {
+      log('  No properties found.');
+      return;
+    }
+
+    // Group by event for display
+    const byEvent = {};
+    for (const p of data.properties) {
+      if (!byEvent[p.event]) byEvent[p.event] = [];
+      byEvent[p.event].push(p.key);
+    }
+
+    for (const [event, keys] of Object.entries(byEvent)) {
+      log(`  ${BOLD}${event}${RESET}`);
+      for (const key of keys) {
+        log(`    ${CYAN}${key}${RESET}`);
+      }
+    }
+
+    log(`\n${DIM}Sampled from last ${data.sample_size} events${RESET}`);
+    log('');
+  } catch (err) {
+    error(`Failed to get properties: ${err.message}`);
+  }
+}
+
+async function cmdDelete(id) {
+  if (!id) error('Usage: npx agent-analytics delete <project-id>');
+
+  const api = requireKey();
+
+  try {
+    await api.deleteProject(id);
+    success(`Project ${id} deleted`);
+  } catch (err) {
+    error(`Failed to delete project: ${err.message}`);
+  }
+}
+
+function cmdDeleteAccount() {
+  heading('Delete Account');
+  log('');
+  log('For security, account deletion must be done from the dashboard.');
+  log(`Visit: ${CYAN}https://app.agentanalytics.sh/settings${RESET}`);
+  log('');
+}
+
+async function cmdRevokeKey() {
+  const api = requireKey();
+
+  try {
+    const data = await api.revokeKey();
+    setApiKey(data.api_key);
+
+    warn('Old API key revoked');
+    success('New API key generated and saved\n');
+    heading('New API key:');
+    log(`${YELLOW}${data.api_key}${RESET}`);
+    log(`${DIM}Saved to ~/.config/agent-analytics/config.json${RESET}\n`);
+    warn('Update your agent with this new key!');
+  } catch (err) {
+    error(`Failed to revoke key: ${err.message}`);
+  }
+}
+
+async function cmdWhoami() {
+  const api = requireKey();
+
+  try {
+    const data = await api.getAccount();
+    heading('Account');
+    log(`  ${BOLD}Email:${RESET}    ${data.email}`);
+    log(`  ${BOLD}GitHub:${RESET}   ${data.github_login || 'N/A'}`);
+    log(`  ${BOLD}Tier:${RESET}     ${data.tier}`);
+    log(`  ${BOLD}Projects:${RESET} ${data.projects_count}/${data.projects_limit}`);
+    if (data.tier === 'pro' && data.monthly_spend_cap_dollars != null) {
+      log(`  ${BOLD}Spend cap:${RESET} $${data.monthly_spend_cap_dollars.toFixed(2)}/month`);
+    }
+    log('');
+  } catch (err) {
+    error(`Failed to get account: ${err.message}`);
+  }
+}
+
+function showHelp() {
+  log(`
+${BOLD}agent-analytics${RESET} — Web analytics your AI agent can read
+
+${BOLD}USAGE${RESET}
+  npx agent-analytics <command> [options]
+
+${BOLD}COMMANDS${RESET}
+  ${CYAN}login${RESET} --token <key> Save your API key
+  ${CYAN}create${RESET} <name>      Create a project and get your snippet
+  ${CYAN}projects${RESET}           List your projects
+  ${CYAN}init${RESET} <name>        Alias for create
+  ${CYAN}delete${RESET} <id>        Delete a project
+  ${CYAN}stats${RESET} <name>       Get stats for a project
+  ${CYAN}events${RESET} <name>      Get recent events
+  ${CYAN}properties-received${RESET} <name>  Show property keys per event
+  ${CYAN}whoami${RESET}             Show current account
+  ${CYAN}revoke-key${RESET}         Revoke and regenerate API key
+  ${CYAN}delete-account${RESET}     Delete your account (opens dashboard)
+
+${BOLD}OPTIONS${RESET}
+  --days <N>         Days of data (default: 7)
+  --limit <N>        Max events to return (default: 100)
+  --domain <url>     Your site domain (required for create)
+  --since <date>     ISO date for properties-received (default: 7 days)
+  --sample <N>       Max events to sample (default: 5000)
+
+${BOLD}ENVIRONMENT${RESET}
+  AGENT_ANALYTICS_API_KEY    API key (overrides config file)
+  AGENT_ANALYTICS_URL    Custom API URL
+
+${BOLD}EXAMPLES${RESET}
+  ${DIM}# First time: save your API key (from app.agentanalytics.sh)${RESET}
+  npx agent-analytics login --token aak_your_key
+
+  ${DIM}# Create a project${RESET}
+  npx agent-analytics create my-site --domain https://mysite.com
+
+  ${DIM}# Check how your site is doing${RESET}
+  npx agent-analytics stats my-site --days 30
+
+  ${DIM}# Your agent can also use the API directly${RESET}
+  curl "https://api.agentanalytics.sh/stats?project=my-site&days=7" \\
+    -H "X-API-Key: \$AGENT_ANALYTICS_API_KEY"
+
+${DIM}https://agentanalytics.sh${RESET}
+`);
+}
+
+// ==================== MAIN ====================
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getArg(flag) {
+  const idx = args.indexOf(flag);
+  return idx > -1 && args[idx + 1] ? args[idx + 1] : null;
+}
+
+try {
+  switch (command) {
+    case 'login':
+      await cmdLogin(getArg('--token'));
+      break;
+    case 'create':
+    case 'init':
+      await cmdCreate(args[1], getArg('--domain'));
+      break;
+    case 'projects':
+    case 'list':
+      await cmdProjects();
+      break;
+    case 'stats':
+      await cmdStats(args[1], parseInt(getArg('--days') || '7'));
+      break;
+    case 'events':
+      await cmdEvents(args[1], {
+        days: parseInt(getArg('--days') || '7'),
+        limit: parseInt(getArg('--limit') || '100'),
+      });
+      break;
+    case 'properties-received':
+      await cmdPropertiesReceived(args[1], {
+        since: getArg('--since'),
+        sample: getArg('--sample') ? parseInt(getArg('--sample')) : undefined,
+      });
+      break;
+    case 'delete':
+      await cmdDelete(args[1]);
+      break;
+    case 'revoke-key':
+      await cmdRevokeKey();
+      break;
+    case 'delete-account':
+      cmdDeleteAccount();
+      break;
+    case 'whoami':
+      await cmdWhoami();
+      break;
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      showHelp();
+      break;
+    default:
+      error(`Unknown command: ${command}. Run: npx agent-analytics help`);
+  }
+} catch (err) {
+  error(err.message);
+}

package/lib/api.mjs

@@ -0,0 +1,90 @@
+/**
+ * Agent Analytics API client.
+ * Zero dependencies — uses native fetch.
+ */
+
+const BASE_URL = 'https://api.agentanalytics.sh';
+
+export class AgentAnalyticsAPI {
+  constructor(apiKey, baseUrl = BASE_URL) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  async request(method, path, body, { returnHeaders = false } = {}) {
+    const opts = {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+    };
+
+    if (this.apiKey) {
+      opts.headers['X-API-Key'] = this.apiKey;
+    }
+
+    if (body) {
+      opts.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(`${this.baseUrl}${path}`, opts);
+    const data = await res.json();
+
+    if (!res.ok) {
+      throw new Error(data.error || `HTTP ${res.status}`);
+    }
+
+    if (returnHeaders) {
+      const headers = {};
+      res.headers.forEach((v, k) => { headers[k] = v; });
+      return { data, headers };
+    }
+
+    return data;
+  }
+
+  // Account
+  async getAccount() {
+    return this.request('GET', '/account');
+  }
+
+  async revokeKey() {
+    return this.request('POST', '/account/revoke-key');
+  }
+
+  // Projects
+  async createProject(name, allowedOrigins = '*') {
+    return this.request('POST', '/projects', {
+      name,
+      allowed_origins: allowedOrigins,
+    });
+  }
+
+  async listProjects() {
+    return this.request('GET', '/projects');
+  }
+
+  async deleteProject(id) {
+    return this.request('DELETE', `/projects/${id}`);
+  }
+
+  // Stats
+  async getStats(project, days = 7, { returnHeaders = false } = {}) {
+    return this.request('GET', `/stats?project=${encodeURIComponent(project)}&days=${days}`, undefined, { returnHeaders });
+  }
+
+  async getEvents(project, { event, days = 7, limit = 100 } = {}) {
+    let qs = `project=${encodeURIComponent(project)}&days=${days}&limit=${limit}`;
+    if (event) qs += `&event=${encodeURIComponent(event)}`;
+    return this.request('GET', `/events?${qs}`);
+  }
+
+  async getProperties(project, days = 30) {
+    return this.request('GET', `/properties?project=${encodeURIComponent(project)}&days=${days}`);
+  }
+
+  async getPropertiesReceived(project, { since, sample } = {}) {
+    let qs = `project=${encodeURIComponent(project)}`;
+    if (since) qs += `&since=${encodeURIComponent(since)}`;
+    if (sample) qs += `&sample=${sample}`;
+    return this.request('GET', `/properties/received?${qs}`);
+  }
+}

package/lib/config.mjs

@@ -0,0 +1,40 @@
+/**
+ * Config management — stores API key locally.
+ * ~/.config/agent-analytics/config.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CONFIG_DIR = join(homedir(), '.config', 'agent-analytics');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+export function getConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function getApiKey() {
+  const config = getConfig();
+  return process.env.AGENT_ANALYTICS_API_KEY || config.api_key || null;
+}
+
+export function setApiKey(key) {
+  const config = getConfig();
+  config.api_key = key;
+  saveConfig(config);
+}
+
+export function getBaseUrl() {
+  const config = getConfig();
+  return process.env.AGENT_ANALYTICS_URL || config.base_url || 'https://api.agentanalytics.sh';
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@agent-analytics/cli",
+  "version": "0.1.7",
+  "description": "Web analytics your AI agent can read. CLI for managing projects and querying stats.",
+  "bin": {
+    "agent-analytics": "./bin/cli.mjs"
+  },
+  "type": "module",
+  "keywords": [
+    "analytics",
+    "ai",
+    "agent",
+    "cli",
+    "web-analytics"
+  ],
+  "author": "Agent Analytics <danny@animaapp.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Agent-Analytics/agent-analytics-cli"
+  },
+  "homepage": "https://agentanalytics.sh",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}