@adgine/geo-cli 1.2.8

package/README.md

@@ -0,0 +1,93 @@
+# @adgine/geo-cli
+
+Run the **Adgine GEO skill suite** from your terminal — or install the skills into an
+AI agent (Claude Code, Cursor, …). This is a thin Node wrapper over the official
+`adgine-geo-skills` Python scripts, published to npm so you can `npm i -g` instead of
+cloning a repo. Bring your own `GEO_API_KEY`.
+
+## Requirements
+
+- **Node.js ≥ 18**
+- **Python ≥ 3.9** on your PATH (the CLI wraps Python skills)
+- A **GEO API key** (`geo_sk_live_…`) from <https://platform.adgine.ai>
+
+## Install
+
+```bash
+npm install -g @adgine/geo-cli
+# or run without installing:
+npx @adgine/geo-cli --help
+```
+
+## Quick start
+
+```bash
+# 1. Save your key once (stored in ~/.adgine/config.json, mode 0600)
+adgine-geo config set-key geo_sk_live_xxxxxxxx
+
+# 2. Check your environment (Python, key validity, optional deps)
+adgine-geo doctor
+
+# 3. Explore what's available
+adgine-geo list
+
+# 4. Run a skill action
+adgine-geo projects list_projects
+adgine-geo visibility get_visibility score --project-id <id>
+```
+
+The key is passed to the Python scripts via the environment at run time — no `.env`
+file is written into the package, and nothing is added to your shell rc files.
+
+## Usage
+
+```
+adgine-geo <skill> <action> [options]    Run a skill action (options pass through to Python)
+adgine-geo list                          List all skills and their actions
+adgine-geo <skill>                       Show a skill's actions
+adgine-geo <skill> <action> --help       Show a script's own options (argparse)
+adgine-geo doctor [--install-audit-deps] Check Python, API key, and optional deps
+adgine-geo config set-key <key>          Save GEO_API_KEY
+adgine-geo config set-base-url <url>     Override the API base URL (self-hosted)
+adgine-geo config get                    Show current config (key masked)
+adgine-geo config path                   Print the config file path
+adgine-geo skills install [--target d]   Install the skills into an AI agent's skills dir
+adgine-geo --version                     Print version
+```
+
+Configuration precedence: environment variables (`GEO_API_KEY`, `GEO_API_BASE_URL`)
+override `~/.adgine/config.json`.
+
+## Using it with an AI agent
+
+`adgine-geo skills install` copies the skill folders into an agent's skills directory
+(the same layout the agent would get from a git clone) and writes your key into a local
+`.env` there:
+
+```bash
+adgine-geo skills install --target ~/.claude/skills/adgine-geo
+```
+
+With no `--target`, it installs to the default Claude Code user skills directory and
+prints other common locations.
+
+## Skills that don't need a key
+
+- **`site-audit`** — standalone GEO technical audit of any public URL (local crawl + PDF).
+  Needs a few extra Python packages: `adgine-geo doctor --install-audit-deps`.
+- **`docs`** — links the official Adgine user manual.
+
+## How it works
+
+```
+adgine-geo (Node bin)
+  └─ spawns python3 skills/adgine-geo-<skill>/scripts/<action>.py <args...>
+     with GEO_API_KEY injected into the child environment
+```
+
+The `skills/` payload is the upstream `adgine-geo-skills` suite, bundled at publish
+time. The npm package version tracks the suite's `VERSION`.
+
+## License
+
+MIT

package/bin/adgine-geo.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * adgine-geo — run the Adgine GEO skill suite from your terminal, or install
+ * the skills into an AI agent. Thin Node wrapper over the bundled Python
+ * skills; configure your key once with `adgine-geo config set-key`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const config = require('../src/config');
+const runner = require('../src/runner');
+const manifest = require('../src/manifest');
+const install = require('../src/install');
+const doctor = require('../src/doctor');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function version() {
+  try {
+    return fs.readFileSync(path.join(runner.SKILLS_DIR, 'VERSION'), 'utf8').trim();
+  } catch {
+    try {
+      return require(path.join(PKG_ROOT, 'package.json')).version;
+    } catch {
+      return '0.0.0';
+    }
+  }
+}
+
+const HELP_COMMANDS = new Set(['help', '-h', '--help']);
+
+function topLevelHelp() {
+  return `adgine-geo v${version()} — Adgine GEO skills CLI
+
+Usage:
+  adgine-geo <skill> <action> [options]   Run a skill action (Python passthrough)
+  adgine-geo list                         List all skills and their actions
+  adgine-geo doctor [--install-audit-deps] Check Python, API key, and deps
+  adgine-geo config set-key <key>         Save your GEO_API_KEY (~/.adgine/config.json)
+  adgine-geo config set-base-url <url>    Override the API base URL
+  adgine-geo config get                   Show current config
+  adgine-geo config path                  Print the config file path
+  adgine-geo skills install [--target d]  Install skills into an AI agent's skills dir
+  adgine-geo --version                    Print version
+
+Examples:
+  adgine-geo config set-key geo_sk_live_xxx
+  adgine-geo projects list_projects
+  adgine-geo visibility get_visibility --project-id <id>
+  adgine-geo site-audit geo_collect https://example.com
+  adgine-geo projects list_projects --help  (passes --help to the Python script)
+
+Docs: https://platform.adgine.ai`;
+}
+
+function cmdList() {
+  const skills = manifest.buildManifest();
+  process.stdout.write(`adgine-geo v${version()} — ${skills.length} skills\n\n`);
+  for (const s of skills) {
+    process.stdout.write(`  ${s.skill}\n`);
+    if (s.description) process.stdout.write(`    ${s.description}\n`);
+    if (s.actions.length) {
+      process.stdout.write(`    actions: ${s.actions.join(', ')}\n`);
+    } else {
+      process.stdout.write(`    (no runnable actions — documentation skill)\n`);
+    }
+    process.stdout.write('\n');
+  }
+  process.stdout.write("Run 'adgine-geo <skill> <action> --help' for a script's options.\n");
+  return 0;
+}
+
+function skillHelp(entry) {
+  process.stdout.write(`adgine-geo ${entry.skill}\n`);
+  if (entry.description) process.stdout.write(`  ${entry.description}\n`);
+  process.stdout.write('\n');
+  if (entry.actions.length) {
+    process.stdout.write('Actions:\n');
+    for (const a of entry.actions) {
+      process.stdout.write(`  adgine-geo ${entry.skill} ${a}\n`);
+    }
+    process.stdout.write(
+      `\nRun 'adgine-geo ${entry.skill} <action> --help' for options.\n`
+    );
+  } else {
+    process.stdout.write('This skill has no runnable actions (documentation only).\n');
+  }
+  return 0;
+}
+
+function cmdConfig(args) {
+  const sub = args[0];
+  switch (sub) {
+    case 'set-key': {
+      const key = args[1];
+      if (!key) {
+        process.stderr.write('Usage: adgine-geo config set-key <geo_sk_live_...>\n');
+        return 2;
+      }
+      if (!key.startsWith('geo_sk_')) {
+        process.stderr.write(
+          `WARNING: key does not start with 'geo_sk_' (got ${key.slice(0, 8)}...). Saving anyway.\n`
+        );
+      }
+      config.setKey(key);
+      process.stdout.write(`Saved GEO_API_KEY to ${config.CONFIG_PATH}\n`);
+      process.stdout.write("Verify with: adgine-geo doctor\n");
+      return 0;
+    }
+    case 'set-base-url': {
+      const url = args[1];
+      if (!url) {
+        process.stderr.write('Usage: adgine-geo config set-base-url <url>\n');
+        return 2;
+      }
+      config.setBaseUrl(url);
+      process.stdout.write(`Saved base URL: ${config.getBaseUrl()}\n`);
+      return 0;
+    }
+    case 'get': {
+      const key = config.getKey();
+      process.stdout.write(`config file: ${config.CONFIG_PATH}\n`);
+      process.stdout.write(`api key:     ${config.maskKey(key)}${key ? ` (from ${config.keySource()})` : ''}\n`);
+      process.stdout.write(`base url:    ${config.getBaseUrl()}\n`);
+      return 0;
+    }
+    case 'path':
+      process.stdout.write(config.CONFIG_PATH + '\n');
+      return 0;
+    default:
+      process.stderr.write(
+        'Usage: adgine-geo config <set-key|set-base-url|get|path>\n'
+      );
+      return sub ? 2 : 0;
+  }
+}
+
+function cmdSkills(args) {
+  const sub = args[0];
+  if (sub !== 'install') {
+    process.stderr.write('Usage: adgine-geo skills install [--target <dir>]\n');
+    return sub ? 2 : 0;
+  }
+  const rest = args.slice(1);
+  let target;
+  const ti = rest.indexOf('--target');
+  if (ti !== -1) target = rest[ti + 1];
+
+  if (!target) {
+    target = install.defaultTargets()[0].dir;
+    process.stdout.write(
+      `No --target given; installing to the default Claude Code skills dir.\n` +
+        `Other common targets:\n`
+    );
+    for (const t of install.defaultTargets()) {
+      process.stdout.write(`  ${t.label}: ${t.dir}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  const dest = install.installTo(target);
+  const key = config.getKey();
+  process.stdout.write(`Installed ${manifest.buildManifest().length} skills to ${dest}\n`);
+  if (key) {
+    process.stdout.write(`Wrote GEO_API_KEY to ${path.join(dest, '.env')}\n`);
+  } else {
+    process.stdout.write(
+      `No API key configured yet. Set one, then re-run install (or edit ${path.join(dest, '.env')}):\n` +
+        `  adgine-geo config set-key geo_sk_live_xxx\n`
+    );
+  }
+  return 0;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || HELP_COMMANDS.has(argv[0])) {
+    process.stdout.write(topLevelHelp() + '\n');
+    return 0;
+  }
+  if (argv[0] === '--version' || argv[0] === '-V') {
+    process.stdout.write(version() + '\n');
+    return 0;
+  }
+
+  const [command, ...rest] = argv;
+
+  switch (command) {
+    case 'list':
+      return cmdList();
+    case 'config':
+      return cmdConfig(rest);
+    case 'skills':
+      return cmdSkills(rest);
+    case 'doctor':
+      return doctor.run({ installAudit: rest.includes('--install-audit-deps') });
+    default: {
+      // Treat as: <skill> <action> [passthrough args]
+      const entry = manifest.findSkill(command);
+      if (!entry) {
+        process.stderr.write(
+          `ERROR: unknown command or skill '${command}'.\n` +
+            "  Run 'adgine-geo list' to see available skills, or 'adgine-geo --help'.\n"
+        );
+        return 127;
+      }
+      const action = rest[0];
+      if (!action || HELP_COMMANDS.has(action)) {
+        return skillHelp(entry);
+      }
+      return runner.runSkillAction(entry.skill, action, rest.slice(1));
+    }
+  }
+}
+
+main()
+  .then((code) => process.exit(code || 0))
+  .catch((err) => {
+    process.stderr.write(`ERROR: ${err && err.stack ? err.stack : err}\n`);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@adgine/geo-cli",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.2.8",
+  "description": "Adgine GEO skills as a CLI — run the full adgine-geo skill suite from your terminal or install them into an AI agent. Wraps the Python skills; bring your own GEO_API_KEY.",
+  "keywords": [
+    "adgine",
+    "geo",
+    "aeo",
+    "ai-visibility",
+    "cli",
+    "skills",
+    "ai-agent",
+    "generative-engine-optimization"
+  ],
+  "homepage": "https://platform.adgine.ai",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "adgine-geo": "bin/adgine-geo.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md"
+  ],
+  "scripts": {
+    "sync-skills": "node scripts/sync-skills.js",
+    "sync-version": "node scripts/sync-version.js",
+    "prepublishOnly": "node scripts/sync-skills.js && node scripts/sync-version.js"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/.env.example

@@ -0,0 +1,11 @@
+# GEO Skills — Environment Variables
+# Copy this file to .env and fill in your values.
+# See SETUP.md for detailed instructions per agent tool.
+
+# Required: Your GEO Platform API Key (user-level, grants access to ALL your projects)
+# Get it at: https://platform.adgine.ai
+GEO_API_KEY=geo_sk_live_YOUR_KEY_HERE
+
+
+# 可选：自定义 API 端点（默认生产环境）
+# GEO_API_BASE_URL=https://platform.adgine.ai

package/skills/README.md

@@ -0,0 +1,247 @@
+# adgine-geo-skills
+
+Agent Skills are folders of instructions, scripts, and resources that AI agents load to perform specialized tasks in a repeatable way. This repository packages the full [Adgine GEO platform](https://platform.adgine.ai) workflow as a set of skills — from setting up a project and measuring AI visibility, to generating optimized content and publishing it to WordPress.
+
+**Works with all mainstream AI agents.** Supports [WorkBuddy](https://workbuddy.ai), [Codex](https://openai.com/codex), [OpenClaw](https://github.com/openclaw/openclaw), and [Hermes](https://github.com/hermes-agent/hermes).
+
+**Current version:** [`v1.0.2`](VERSION) · [All releases](https://github.com/adgine-ai/adgine-geo-skills/releases)
+
+---
+
+## Install
+
+The install prompt is the same for every supported agent — send it directly to your agent of choice:
+
+```
+Install skills from https://github.com/adgine-ai/adgine-geo-skills
+```
+
+Known compatible agents:
+
+- **[WorkBuddy](https://workbuddy.ai)**
+- **[Codex](https://openai.com/codex)**
+- **[OpenClaw](https://github.com/openclaw/openclaw)**
+- **[Hermes](https://github.com/hermes-agent/hermes)**
+
+After the agent finishes installing, paste your GEO API key in chat (e.g. *"my GEO API key is geo_sk_live_xxx, please configure it"*). The agent will run the included `setup.py` helper to write the key to a local, gitignored `.env` file at the skills repo root — not to your shell rc, not to the agent's global config.
+
+### Manual install (advanced)
+
+Clone the repo and run the setup helper yourself:
+
+```bash
+git clone https://github.com/adgine-ai/adgine-geo-skills.git
+cd adgine-geo-skills
+
+# One-shot setup — writes your API key to a local .env (gitignored):
+python3 setup.py <YOUR_GEO_API_KEY>
+# ...or run the interactive wizard:
+python3 setup.py
+```
+
+All scripts auto-load `GEO_API_KEY` from `.env` on import — no `export`, no shell rc edits, no terminal restart needed.
+
+---
+
+## Updates
+
+The installed version is recorded in the [`VERSION`](VERSION) file at the repo root. Releases are published at [github.com/adgine-ai/adgine-geo-skills/releases](https://github.com/adgine-ai/adgine-geo-skills/releases).
+
+### For AI agents — how to check and apply updates
+
+Use the following steps whenever the user asks whether skills are up to date, or to update skills:
+
+**Step 1 — Read the installed version**
+
+```bash
+cat "$(find ~ -name VERSION -path '*/adgine-geo-skills/VERSION' 2>/dev/null | head -1)"
+```
+
+**Step 2 — Fetch the latest release from GitHub**
+
+```bash
+curl -s https://api.github.com/repos/adgine-ai/adgine-geo-skills/releases/latest
+```
+
+Key fields to read from the response:
+- `tag_name` — latest version (e.g. `v1.3.0`)
+- `name` — release title
+- `body` — changelog / release notes
+- `published_at` — release date
+
+Alternatively, fetch just the raw version string (no JSON parsing needed):
+
+```bash
+curl -s https://raw.githubusercontent.com/adgine-ai/adgine-geo-skills/main/VERSION
+```
+
+**Step 3 — Present result to user**
+
+- If versions match: report that skills are up to date and show the current version.
+- If behind: show the current version, the latest version, and the release notes from `body`. Ask the user if they want to update.
+
+**Step 4 — Apply update (if requested)**
+
+```bash
+cd <skills-repo-path>
+git pull
+```
+
+The `.env` file (API key) is gitignored and is never modified by `git pull`. No reconfiguration needed after updating.
+
+### User-facing prompt
+
+Users can trigger a version check or update with natural language:
+
+> *"Are my Adgine skills up to date?"*  
+> *"Check for skill updates."*  
+> *"Update my Adgine skills to the latest version."*
+
+---
+
+## What is GEO?
+
+**Generative Engine Optimization (GEO)** is the practice of optimizing your brand and content to be cited, referenced, and recommended by AI search engines — ChatGPT, Perplexity, Google AI Overviews, Gemini, and more. These skills give you programmatic access to the full GEO workflow through natural language, with your agent as the interface.
+
+---
+
+## Skills
+
+| Skill | What it does |
+|---|---|
+| [`adgine-geo-projects`](adgine-geo-projects/) | List, create, update, delete projects; manage competitors; verify auth; configure API key |
+| [`adgine-geo-dashboard`](adgine-geo-dashboard/) | Project snapshot — visibility score, aggregate metrics, 7-day trend, integration health |
+| [`adgine-geo-analytics`](adgine-geo-analytics/) | Traffic overview — GA4 sessions, active users, source breakdown, AI referral summary |
+| [`adgine-geo-aiagent`](adgine-geo-aiagent/) | AI bot & human traffic deep drill-down — 27 endpoints: per-bot KPIs, platform rankings, Sankey flows, raw event logs, per-page deep dives (KPI / logs / platforms / PageSpeed) |
+| [`adgine-geo-visibility`](adgine-geo-visibility/) | Deep AI visibility analytics — Visibility Score, Share of Voice, Average Position, competitor matrix, topic/prompt-level metrics, historical AI execution details & full responses |
+| [`adgine-geo-citation`](adgine-geo-citation/) | Citation tests across ChatGPT / Perplexity / Google AIO / Gemini; brand mention rates, cited URLs, full AI reply text |
+| [`adgine-geo-brand`](adgine-geo-brand/) | Generate and manage AI-facing brand profiles — intro, ICP, competitor analysis, author persona, voice & tone, writing rules; list/inspect/retry brand generation jobs |
+| [`adgine-geo-topics`](adgine-geo-topics/) | Create and manage topics & AI search prompts; batch-generate prompts with AI; cross-topic prompt listing |
+| [`adgine-geo-content`](adgine-geo-content/) | Full content pipeline — generate titles, outlines, and full GEO-optimized articles; manage content library; inspect and retry background jobs |
+| [`adgine-geo-performance`](adgine-geo-performance/) | Per-page AI crawlability, optimization scores, and content health checks (mobile/desktop) |
+| [`adgine-geo-opportunities`](adgine-geo-opportunities/) | AI-discovered content gaps and optimization opportunities ranked by impact — relevance, traffic, competition, urgency, AI citation scores |
+| [`adgine-geo-integrations`](adgine-geo-integrations/) | Connect GA4 (OAuth) and Cloudflare; deploy AI crawler tracking Worker; sync traffic data; query integration-specific data |
+| [`adgine-geo-wordpress`](adgine-geo-wordpress/) | Publish GEO articles to WordPress; manage credentials & categories; track publish history; update existing posts |
+| [`adgine-geo-saas`](adgine-geo-saas/) | Check subdomain availability; create and track SaaS-hosted website deployments |
+| [`adgine-geo-billing`](adgine-geo-billing/) | View plan, status, renewal date, remaining credits, and credits pricing |
+| [`adgine-geo-docs`](adgine-geo-docs/) | Adgine platform user manual (使用手册) — hosted PDF, no API key required |
+| [`adgine-geo-site-audit`](adgine-geo-site-audit/) | **Standalone** GEO technical audit for any public URL — 5-dimension 30-item checklist, local crawl, PDF report export. No API key required |
+
+Each skill is self-contained in its own folder with a `SKILL.md` file containing the instructions and metadata that agents use for tool routing and intent matching.
+
+---
+
+## Repository Structure
+
+```
+adgine-geo-skills/
+├── VERSION                        # Current release version
+├── setup.py                       # API key configuration helper
+├── .env.example                   # Environment variable template
+├── adgine-geo-<domain>/
+│   ├── SKILL.md                   # Agent skill definition — YAML frontmatter (name, description) + usage instructions
+│   ├── WORKFLOW.md                # (some skills) End-to-end workflow guide
+│   └── scripts/
+│       ├── _client.py             # Shared API client for the domain
+│       └── *.py                   # One script per operation
+├── adgine-geo-site-audit/
+│   ├── SKILL.md
+│   ├── README.md                  # Site audit-specific docs
+│   ├── requirements.txt           # Standalone dependencies (curl_cffi, bs4, reportlab, etc.)
+│   ├── scripts/                   # geo_collect, geo_score, geo_visibility, render_report_pdf, etc.
+│   └── tests/                     # Unit tests for site audit modules
+└── ref/                           # Reference documentation (Chinese)
+```
+
+---
+
+## Setup
+
+### 1. Get your API key
+
+Sign in at [platform.adgine.ai](https://platform.adgine.ai) and generate an API key.
+
+### 2. Configure environment
+
+Use the included setup helper — it writes the key to `<repo>/.env` and verifies it:
+
+```bash
+python3 setup.py <YOUR_GEO_API_KEY>     # non-interactive (good for AI agents)
+python3 setup.py                         # interactive wizard
+```
+
+Prefer to do it manually? Copy the template and edit:
+
+```bash
+cp .env.example .env
+# then edit .env and set GEO_API_KEY=geo_sk_live_YOUR_KEY_HERE
+```
+
+All scripts read `.env` automatically on import — no `export` needed.
+
+### 3. Find your project ID
+
+```bash
+python3 adgine-geo-projects/scripts/list_projects.py
+export GEO_PROJECT_ID=<your-project-id>
+```
+
+### 4. Ask your agent
+
+Once the skills are loaded, use natural language:
+
+> *"What's my AI visibility score this week?"*  
+> *"Generate a brand profile for my project."*  
+> *"Which AI platforms are crawling my site the most?"*  
+> *"Publish article 123 to my WordPress site."*  
+> *"Audit example.com for GEO score and export a PDF."*  
+> *"What optimization opportunities does my project have?"*
+
+Or run scripts directly:
+
+```bash
+# Dashboard snapshot
+python3 adgine-geo-dashboard/scripts/get_overview.py
+
+# AI visibility score
+python3 adgine-geo-visibility/scripts/get_visibility.py score
+
+# AI bot traffic platform ranking
+python3 adgine-geo-aiagent/scripts/bot_traffic.py platforms
+
+# Generate article outline
+python3 adgine-geo-content/scripts/generate_outline.py --topic-id <id> --prompt-ids <id1,id2>
+
+# Standalone site audit (no API key needed)
+python3 adgine-geo-site-audit/scripts/geo_collect.py https://example.com --max-subpages 20
+
+# Check credits balance
+python3 adgine-geo-billing/scripts/get_credits.py
+```
+
+---
+
+## Authentication
+
+All scripts read from the `GEO_API_KEY` environment variable. Never hardcode your key or commit it to version control. The `.env` file is gitignored by default.
+
+---
+
+## Requirements
+
+- Python 3.9+
+- `requests` (`pip install requests`)
+- An [Adgine GEO](https://platform.adgine.ai) account with an active API key (not required for `adgine-geo-site-audit` and `adgine-geo-docs`)
+- **Site audit only:** additional packages — run `pip install -r adgine-geo-site-audit/requirements.txt`
+
+---
+
+## Disclaimer
+
+These skills are provided for use with the Adgine GEO platform API. Always test in your own environment before relying on them for critical workflows.
+
+---
+
+## License
+
+See [LICENSE](LICENSE) for details.