@mentio_website/cli 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @mentio/cli
+
+Mentio from your terminal — see how AI answer engines (ChatGPT, Claude, Perplexity, Google AI) mention and cite your brand.
+
+## Install
+
+```bash
+npm install -g @mentio/cli
+# or run without installing:
+npx @mentio/cli --help
+```
+
+Requires Node ≥ 18.
+
+## Login
+
+You need a Mentio **API key** (`gtk_…`).
+
+```bash
+mentio login          # prompts for API base URL + API key
+```
+
+Credentials are stored in `~/.mentio/config.json` (chmod 600). You can also pass `--key` per command or set `MENTIO_API_KEY`.
+
+## Commands
+
+```
+mentio projects                 # list your projects
+mentio add example.com --desc "What your brand does" --competitors a.com,b.com
+
+mentio visibility <id>          # visibility, citation rate, share of voice
+mentio gaps <id>                # prompts where you're absent + who's cited instead
+mentio sources <id>             # domains the engines cite for your topics
+mentio timeseries <id>          # visibility over time
+mentio recommend <id> --lang en # actions + ready-to-use optimization prompts
+mentio probe <id>               # trigger a new analysis run
+
+mentio audit <id>               # on-page SEO audit + PageSpeed (free)
+mentio queries <id>             # real Google Search Console queries (GSC connected)
+
+mentio account                  # plan + credit balance
+```
+
+Add `--json` to any command for scriptable output:
+
+```bash
+mentio visibility 2 --json | jq '.overall.visibility_rate'
+```
+
+## Flags
+
+- `--json` — raw JSON output
+- `--base <url>` — override API base URL (self-host)
+- `--key <apiKey>` — override API key (or `MENTIO_API_KEY`)
+- `-h, --help` · `-v, --version`
+
+MIT · https://usementio.eu

package/bin/mentio.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// Mentio CLI — talk to the Mentio API from your terminal.
+// Zero dependencies: Node >= 18 (global fetch). Config in ~/.mentio/config.json.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+
+const VERSION = "0.1.0";
+const DEFAULT_BASE = "https://api-production-c8ce.up.railway.app";
+const CONFIG_DIR = path.join(os.homedir(), ".mentio");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+// ── colors (respect NO_COLOR / non-TTY) ─────────────────────────────────────
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const c = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const orange = (s) => c("38;5;208", s);
+const dim = (s) => c("2", s);
+const bold = (s) => c("1", s);
+const green = (s) => c("32", s);
+const red = (s) => c("31", s);
+
+// ── config ──────────────────────────────────────────────────────────────────
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+  try {
+    fs.chmodSync(CONFIG_FILE, 0o600);
+  } catch {}
+}
+
+// ── args ─────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+const flags = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a.startsWith("--")) {
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      flags[key] = next;
+      i++;
+    } else flags[key] = true;
+  } else positional.push(a);
+}
+const cmd = positional[0];
+
+function die(msg) {
+  console.error(red("✖ ") + msg);
+  process.exit(1);
+}
+
+// ── HTTP ─────────────────────────────────────────────────────────────────────
+async function api(pathname, { method = "GET", body } = {}) {
+  const cfg = loadConfig();
+  const key = flags.key || process.env.MENTIO_API_KEY || cfg.key;
+  if (!key) die("Not logged in. Run: " + bold("mentio login") + "  (or pass --key / MENTIO_API_KEY)");
+  const base = flags.base || cfg.base || DEFAULT_BASE;
+  let res;
+  try {
+    res = await fetch(base + pathname, {
+      method,
+      headers: {
+        Authorization: "Bearer " + key,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (e) {
+    die("Network error: " + e.message);
+  }
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = text;
+  }
+  if (!res.ok) {
+    const detail = data && data.error ? data.error : typeof data === "string" ? data : JSON.stringify(data);
+    if (res.status === 401) die("Unauthorized (" + res.status + "). Check your API key: mentio login");
+    die(`HTTP ${res.status}: ${detail}`);
+  }
+  return data;
+}
+
+// ── formatting ────────────────────────────────────────────────────────────────
+function print(data) {
+  if (flags.json) console.log(JSON.stringify(data, null, 2));
+  return flags.json;
+}
+const pct = (v) => (v == null ? "—" : (Math.round(v * 1000) / 10).toFixed(1) + "%");
+function table(rows, headers) {
+  if (!rows.length) return console.log(dim("(none)"));
+  const cols = headers.map((h) => h.label);
+  const widths = headers.map((h, i) =>
+    Math.max(cols[i].length, ...rows.map((r) => String(h.get(r) ?? "").length))
+  );
+  const line = (cells) => cells.map((cell, i) => String(cell ?? "").padEnd(widths[i])).join("  ");
+  console.log(dim(line(cols)));
+  for (const r of rows) console.log(line(headers.map((h) => h.get(r))));
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+async function login() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q, def) => new Promise((r) => rl.question(q, (a) => r(a.trim() || def)));
+  const cfg = loadConfig();
+  const base = flags.base || (await ask(`API base URL [${cfg.base || DEFAULT_BASE}]: `, cfg.base || DEFAULT_BASE));
+  const key = flags.key || (await ask("API key (gtk_…): ", cfg.key));
+  rl.close();
+  if (!key) die("No API key provided.");
+  saveConfig({ ...cfg, base, key });
+  // verify
+  try {
+    const acc = await apiWith(base, key, "/api/v1/billing/account");
+    console.log(green("✓ ") + `Logged in. Plan: ${bold(acc.plan || "?")} · credits: ${acc.credits ?? "?"}`);
+  } catch {
+    console.log(green("✓ ") + "Saved credentials to " + dim(CONFIG_FILE));
+  }
+}
+async function apiWith(base, key, pathname) {
+  const res = await fetch(base + pathname, { headers: { Authorization: "Bearer " + key } });
+  if (!res.ok) throw new Error(String(res.status));
+  return res.json();
+}
+
+function logout() {
+  try {
+    fs.rmSync(CONFIG_FILE);
+  } catch {}
+  console.log(green("✓ ") + "Logged out.");
+}
+
+async function account() {
+  const d = await api("/api/v1/billing/account");
+  if (print(d)) return;
+  console.log(`${bold("Plan")}    ${d.plan}`);
+  console.log(`${bold("Credits")} ${d.credits}`);
+}
+
+async function projects() {
+  const { projects } = await api("/api/v1/projects");
+  if (print({ projects })) return;
+  table(projects, [
+    { label: "ID", get: (p) => p.id },
+    { label: "DOMAIN", get: (p) => p.domain },
+    { label: "NAME", get: (p) => p.name },
+    { label: "COMPETITORS", get: (p) => (p.competitors || []).join(", ") },
+  ]);
+}
+
+async function add() {
+  const domain = positional[1];
+  if (!domain) die("Usage: mentio add <domain> [--desc \"...\"] [--competitors a.com,b.com] [--no-run]");
+  const body = {
+    domain,
+    description: flags.desc || flags.description || "",
+    competitors: (flags.competitors || "").split(",").map((s) => s.trim()).filter(Boolean),
+    generate_prompts: true,
+    run: !flags["no-run"],
+  };
+  const d = await api("/api/v1/projects", { method: "POST", body });
+  if (print(d)) return;
+  console.log(green("✓ ") + `Created project ${bold(d.id)} (${d.domain}).`);
+  if (d.run) console.log(dim(`  run ${d.run.run_id} — ${d.run.jobs} probes across ${(d.run.engines || []).join(", ")}`));
+}
+
+function reqId() {
+  const id = positional[1];
+  if (!id) die(`Usage: mentio ${cmd} <projectId>`);
+  return id;
+}
+
+async function visibility() {
+  const d = await api(`/api/v1/projects/${reqId()}/visibility`);
+  if (print(d)) return;
+  const o = d.overall || {};
+  console.log(bold("Overall"));
+  console.log(`  visibility ${orange(pct(o.visibility_rate))}   citation ${pct(o.citation_rate)}   SoV ${pct(o.share_of_voice)}   (${o.probes || 0} probes)`);
+  if ((d.per_engine || []).length) {
+    console.log(bold("\nPer engine"));
+    table(d.per_engine, [
+      { label: "ENGINE", get: (e) => e.engine },
+      { label: "VISIBILITY", get: (e) => pct(e.visibility_rate) },
+      { label: "CITATION", get: (e) => pct(e.citation_rate) },
+      { label: "PROBES", get: (e) => e.probes },
+    ]);
+  }
+}
+
+async function gaps() {
+  const { gaps } = await api(`/api/v1/projects/${reqId()}/gaps`);
+  if (print({ gaps })) return;
+  table(gaps || [], [
+    { label: "PROMPT", get: (g) => (g.prompt || "").slice(0, 60) },
+    { label: "ENGINE", get: (g) => g.engine },
+    { label: "AI CITED", get: (g) => (g.domains || []).slice(0, 3).join(", ") },
+  ]);
+}
+
+async function sources() {
+  const { cited_domains } = await api(`/api/v1/projects/${reqId()}/cited-domains`);
+  if (print({ cited_domains })) return;
+  table(cited_domains || [], [
+    { label: "DOMAIN", get: (s) => s.domain },
+    { label: "CITATIONS", get: (s) => s.count },
+  ]);
+}
+
+async function recommend() {
+  const lang = flags.lang || "en";
+  const d = await api(`/api/v1/projects/${reqId()}/recommendations?lang=${lang}`);
+  if (print(d)) return;
+  if (d.summary) console.log(dim(d.summary) + "\n");
+  console.log(bold("Actions"));
+  for (const r of d.recommendations || []) console.log("  " + orange("—") + " " + r);
+  if ((d.optimization_prompts || []).length) {
+    console.log(bold("\nOptimization prompts"));
+    for (const p of d.optimization_prompts) console.log("  " + dim("›") + " " + p);
+  }
+}
+
+async function audit() {
+  const d = await api(`/api/v1/projects/${reqId()}/seo/audit`);
+  if (print(d)) return;
+  console.log(bold(d.url || "") + "  " + (d.fetched ? green(`HTTP ${d.status}`) : red("unreachable")));
+  if (d.pagespeed) console.log(dim(`PageSpeed — perf ${d.pagespeed.performance} · seo ${d.pagespeed.seo}`));
+  const icon = (s) => (s === "ok" ? green("✓") : s === "fail" ? red("✗") : orange("!"));
+  for (const ch of d.checks || []) console.log(`  ${icon(ch.status)} ${ch.message}`);
+  console.log(dim(`  robots.txt ${d.robots_txt ? "✓" : "—"}   sitemap ${d.sitemap ? "✓" : "—"}`));
+}
+
+async function queries() {
+  const d = await api(`/api/v1/projects/${reqId()}/seo/queries`);
+  if (print(d)) return;
+  table(d.queries || [], [
+    { label: "QUERY", get: (q) => (q.keys || []).join(" ") },
+    { label: "CLICKS", get: (q) => q.clicks },
+    { label: "IMPR", get: (q) => q.impressions },
+    { label: "CTR", get: (q) => ((q.ctr || 0) * 100).toFixed(1) + "%" },
+    { label: "POS", get: (q) => (q.position || 0).toFixed(1) },
+  ]);
+}
+
+async function timeseries() {
+  const d = await api(`/api/v1/projects/${reqId()}/timeseries`);
+  if (print(d)) return;
+  table(d.timeseries || [], [
+    { label: "DATE", get: (t) => t.date || t.day },
+    { label: "VISIBILITY", get: (t) => pct(t.visibility_rate) },
+  ]);
+}
+
+async function probe() {
+  const d = await api(`/api/v1/projects/${reqId()}/probe`, { method: "POST" });
+  if (print(d)) return;
+  console.log(green("✓ ") + `Run started: ${d.run_id} — ${d.jobs} probes (${(d.engines || []).join(", ")}).`);
+}
+
+function help() {
+  console.log(`
+${orange("mentio")} — see how AI answer engines cite your brand.  ${dim("v" + VERSION)}
+
+${bold("Usage")}
+  mentio <command> [args] [--json] [--base <url>] [--key <apiKey>]
+
+${bold("Auth")}
+  login                     Save API base URL + API key to ~/.mentio/config.json
+  logout                    Remove stored credentials
+  account                   Show plan and credit balance
+
+${bold("Projects")}
+  projects                  List your projects
+  add <domain>              Add a project  [--desc "..."] [--competitors a,b] [--no-run]
+
+${bold("GEO metrics")}  ${dim("(need a project id — see: mentio projects)")}
+  visibility <id>           Visibility, citation rate, share of voice (overall + per engine)
+  gaps <id>                 Prompt × engine where you're absent, + who's cited instead
+  sources <id>              Domains the engines cite for your topics
+  timeseries <id>           Visibility over time
+  recommend <id>            Actions + optimization prompts   [--lang en|it]
+  probe <id>                Trigger a new analysis run
+
+${bold("SEO (free)")}
+  audit <id>                On-page audit + PageSpeed
+  queries <id>              Real Google Search Console queries (needs GSC connected)
+
+${bold("Global flags")}
+  --json                    Raw JSON output (scriptable)
+  --base <url>              Override API base URL
+  --key <apiKey>            Override API key (or set MENTIO_API_KEY)
+  -h, --help                This help    ·    -v, --version
+
+${dim("Docs: https://usementio.eu")}
+`);
+}
+
+// ── dispatch ──────────────────────────────────────────────────────────────────
+const commands = {
+  login,
+  logout,
+  account,
+  whoami: account,
+  projects,
+  add,
+  visibility,
+  gaps,
+  sources,
+  recommend,
+  recommendations: recommend,
+  audit,
+  queries,
+  timeseries,
+  probe,
+};
+
+async function main() {
+  if (flags.version || flags.v || cmd === "version") return console.log(VERSION);
+  if (!cmd || flags.help || flags.h || cmd === "help") return help();
+  const fn = commands[cmd];
+  if (!fn) die(`Unknown command: ${cmd}\nRun ${bold("mentio --help")}`);
+  await fn();
+}
+
+main().catch((e) => die(e.message || String(e)));

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mentio_website/cli",
+  "version": "0.1.0",
+  "description": "Mentio CLI — see how AI answer engines cite your brand, from the terminal.",
+  "type": "module",
+  "bin": {
+    "mentio": "bin/mentio.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "mentio",
+    "geo",
+    "generative-engine-optimization",
+    "ai-search",
+    "seo",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://usementio.eu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giacomocavalcabo/mentio.git"
+  }
+}