@prowl-ai/prowl-skill 0.4.0

package/plugins/prowl/lib/state.js

@@ -0,0 +1,237 @@
+'use strict';
+/**
+ * What this session has asked Prowl to do, kept where the next hook can read it.
+ *
+ * `PreToolUse` sees a call start; `PostToolUse` sees it finish several seconds later,
+ * in a different process; the status line renders it in a third. Nothing in a hook
+ * payload carries state between them, so it goes through a file keyed by session.
+ *
+ * **`~/.prowl/` and not the project tree.** The token file already lives there — this
+ * plugin has one home on the machine. A file under the repository would be committed
+ * by someone eventually, and a file under `/tmp` would vanish mid-session.
+ *
+ * **Keyed by `session_id`.** Not by pid: the status-line reference is explicit that a
+ * pid changes on every invocation and defeats exactly this kind of cache.
+ *
+ * Nothing here throws. A hook that raises breaks the operator's turn for a widget,
+ * which is a bad trade in every direction; an unreadable file is an empty state, and
+ * a write that cannot happen is a widget that says less rather than a turn that dies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Where a session's file lives, relative to home. */
+const DIR = ['.prowl', 'status'];
+
+/** How many finished calls the ticker remembers. The array IS the display rule. */
+const RECENT = 5;
+
+/** How long a lock may be held before it is assumed dead. Hooks are short. */
+const LOCK_STALE_MS = 5000;
+
+/** The canonical empty state. Every absent field is absent, never zero. */
+function empty(sessionId) {
+  return {
+    session_id: sessionId || null,
+    updated_at: null,
+    open: {},
+    recent: [],
+    totals: { calls: 0, ok: 0, failed: 0, usd: null },
+    progress: null,
+    server: null,
+    spoken: [],
+  };
+}
+
+/**
+ * A session id becomes a filename, so nothing in it may be a path.
+ *
+ * Separators first, then every run of dots: while they are still separators, `..` is
+ * still recognisable as a traversal.
+ */
+function fileFor(home, sessionId) {
+  const key = String(sessionId || 'unknown')
+    .replace(/[^A-Za-z0-9._-]+/g, '_')
+    .replace(/\.{2,}/g, '_')
+    .replace(/^[._]+/, '')
+    .slice(0, 80);
+  return path.join(home, ...DIR, `${key || 'unknown'}.json`);
+}
+
+/** The recorded state, or an empty one. An unparsable file is an empty one. */
+function read(home, sessionId) {
+  try {
+    const raw = fs.readFileSync(fileFor(home, sessionId), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return empty(sessionId);
+    // A file written by an older shape must not make today's renderer throw.
+    return Object.assign(empty(sessionId), parsed);
+  } catch (e) {
+    return empty(sessionId);
+  }
+}
+
+/**
+ * Write, atomically.
+ *
+ * A temporary file in the same directory and then `rename`, because a reader that
+ * arrives mid-write must see the old document or the new one and never half of
+ * either. The temp name carries the pid so two writers cannot collide on it.
+ */
+function writeAtomic(file, state) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state), 'utf8');
+    fs.renameSync(tmp, file);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Run `fn(state)` under a lock and persist what it returns.
+ *
+ * `rename` alone stops a torn document; it does not stop a lost update, and two calls
+ * finishing in the same instant is the normal case for an agent that batches tool
+ * calls. `mkdir` is the atomic primitive available everywhere, so it is the lock.
+ *
+ * **The lock is never allowed to cost a turn.** After roughly fifty milliseconds the
+ * update proceeds unlocked: a widget that occasionally loses one record is better
+ * than a hook that hangs, and a stale lock left by a killed process is cleared by age
+ * rather than by an operator.
+ */
+function update(home, sessionId, fn) {
+  const file = fileFor(home, sessionId);
+  const lock = `${file}.lock`;
+  let held = false;
+  for (let i = 0; i < 50; i += 1) {
+    try {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.mkdirSync(lock);
+      held = true;
+      break;
+    } catch (e) {
+      try {
+        const age = Date.now() - fs.statSync(lock).mtimeMs;
+        if (age > LOCK_STALE_MS) { fs.rmdirSync(lock); continue; }
+      } catch (e2) { /* it went away between the two calls, which is fine */ }
+      // Busy-wait one millisecond. `Atomics.wait` is the only synchronous sleep a
+      // hook can use, and a hook is synchronous by construction.
+      try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1); } catch (e3) { /* no SAB */ }
+    }
+  }
+  let next;
+  try {
+    next = fn(read(home, sessionId));
+  } catch (e) {
+    next = null;
+  }
+  let ok = false;
+  if (next) {
+    next.updated_at = next.updated_at || new Date().toISOString();
+    ok = writeAtomic(file, next);
+  }
+  if (held) { try { fs.rmdirSync(lock); } catch (e) { /* already gone */ } }
+  return ok ? next : null;
+}
+
+/** A call started. Keyed by `tool_use_id`, so the in-flight count counts calls. */
+function openCall(home, sessionId, rec) {
+  if (!rec || !rec.id) return null;
+  return update(home, sessionId, (s) => {
+    s.session_id = s.session_id || sessionId || null;
+    s.open[rec.id] = { tool: rec.tool || null, at: rec.at || new Date().toISOString() };
+    s.updated_at = rec.at || new Date().toISOString();
+    return s;
+  });
+}
+
+/**
+ * A call finished.
+ *
+ * `ms` is computed only when the start was seen. A plugin installed mid-session, or a
+ * session resumed across a restart, produces a close with no open — and the duration
+ * is then **absent**, never zero. `usd` is added only when the response carried one;
+ * a free tool must not drag the total to a number the server never said.
+ */
+function closeCall(home, sessionId, rec) {
+  if (!rec || !rec.id) return null;
+  return update(home, sessionId, (s) => {
+    const started = s.open[rec.id];
+    delete s.open[rec.id];
+    const at = rec.at || new Date().toISOString();
+    const ms = started && started.at ? Math.max(0, Date.parse(at) - Date.parse(started.at)) : null;
+    const entry = {
+      tool: rec.tool || (started && started.tool) || null,
+      ok: rec.ok !== false,
+      ms: Number.isFinite(ms) ? ms : null,
+      usd: typeof rec.usd === 'number' && Number.isFinite(rec.usd) ? rec.usd : null,
+      at,
+    };
+    s.recent.push(entry);
+    while (s.recent.length > RECENT) s.recent.shift();
+    s.totals.calls += 1;
+    if (entry.ok) s.totals.ok += 1; else s.totals.failed += 1;
+    if (entry.usd !== null) s.totals.usd = (s.totals.usd === null ? 0 : s.totals.usd) + entry.usd;
+    if (typeof rec.progress === 'number') {
+      s.progress = { session_id: rec.progress_session || null, value: rec.progress, at };
+    }
+    // The server's own accounting, when it volunteered it. Kept beside the sum rather
+    // than folded into it: two figures that disagree are a fact worth keeping.
+    if (rec.server && typeof rec.server === 'object') s.server = Object.assign({ at }, rec.server);
+    s.updated_at = at;
+    return s;
+  });
+}
+
+/**
+ * Has this exact thing already been said?
+ *
+ * Returns `true` the first time a fingerprint is seen and `false` afterwards, so a
+ * failing call that the agent retries five times interrupts once. The fingerprint is
+ * recorded by the same write that answers, because two hooks asking at once must not
+ * both be told "first".
+ */
+function claimSpeech(home, sessionId, fingerprint) {
+  if (!fingerprint) return false;
+  let first = false;
+  update(home, sessionId, (s) => {
+    if (s.spoken.includes(fingerprint)) return s;
+    first = true;
+    s.spoken.push(fingerprint);
+    while (s.spoken.length > 50) s.spoken.shift();
+    return s;
+  });
+  return first;
+}
+
+/**
+ * Delete session files older than `maxAgeMs`.
+ *
+ * Without it this directory grows one small file per session forever — the kind of
+ * litter nobody notices until it is thousands of files.
+ */
+function prune(home, nowMs, maxAgeMs) {
+  const dir = path.join(home, ...DIR);
+  let removed = 0;
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      const f = path.join(dir, name);
+      try {
+        if (nowMs - fs.statSync(f).mtimeMs > maxAgeMs) {
+          if (fs.statSync(f).isDirectory()) fs.rmdirSync(f); else fs.unlinkSync(f);
+          removed += 1;
+        }
+      } catch (e) { /* a file that vanished mid-sweep needed no pruning */ }
+    }
+  } catch (e) { /* nothing to prune is the normal case */ }
+  return removed;
+}
+
+module.exports = {
+  empty, fileFor, read, update, openCall, closeCall, claimSpeech, prune,
+  DIR, RECENT, LOCK_STALE_MS,
+};

package/plugins/prowl/skills/prowl/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: prowl
+description: Connects this agent to the Prowl MCP — a single MCP endpoint exposing 448 market-intelligence tools (SEO, backlinks, ads, SERP, web scraping, AI) plus the full Prowl analysis pipeline, billed pay-as-you-go from a USD wallet. Use when researching competitors, pulling SEO/SERP/keyword/backlink data, analyzing ad creative or spend, comparing pricing or funnels, validating a product idea, or any task that needs real market data instead of guesses.
+license: MIT
+compatibility: Requires network access to prowl.chat and a Prowl API token; the bundled MCP config runs `npx mcp-remote` (needs Node.js 18+).
+metadata:
+  author: prowl.chat
+  version: "0.3.0"
+---
+
+# Prowl — market intelligence for your agent
+
+Prowl is a single MCP endpoint that exposes **448 market-intelligence API tools** across 15 providers (DataForSEO, SearchAPI, SerpApi, SpyFu, Majestic, Foreplay, Firecrawl, Exa, Perplexity, Gemini, …) plus the full Prowl pipeline — `prowl_analyze`, async research sessions, recurring schedules, artifacts and exports. Call real data instead of guessing.
+
+- MCP URL: `https://prowl.chat/mcp`
+- Transport: Streamable HTTP
+- Auth header: `Authorization: Bearer prowl_<your_key>`
+
+## Setup (one time)
+
+Prowl API keys (`prowl_...`) are billing-bearing — every metered call debits a USD wallet. Treat the key as a secret; never commit it to a public repo.
+
+1. The human signs up at [https://prowl.chat](https://prowl.chat) (gets $5 starter credit), optionally tops up the wallet, and generates a `prowl_...` key (shown once) under **MCP Home → API keys & config**.
+2. Provide the key to this plugin via either:
+   - environment variable `PROWL_MCP_TOKEN`, or
+   - a token file at `~/.prowl/prowl_mcp_token` (`mkdir -p ~/.prowl && printf '%s' "prowl_YOUR_KEY" > ~/.prowl/prowl_mcp_token && chmod 600 ~/.prowl/prowl_mcp_token`).
+3. The bundled `.mcp.json` reads the token automatically and connects via `mcp-remote`.
+
+For manual per-client setup (Cursor `.cursor/mcp.json`, Claude Code `claude mcp add`, Codex `config.toml`, generic MCP), see the hosted playbook: [https://prowl.chat/mcp/install.md](https://prowl.chat/mcp/install.md).
+
+## Core tools
+
+22 MCP tools front the catalog. The ones that matter day to day:
+
+| Tool | Purpose | Cost |
+|------|---------|------|
+| `prowl_list_tools` | Browse the 448 tools by category | free |
+| `prowl_search_tools` | Semantic search over the catalog | free |
+| `prowl_tool_info` | JSON input schema + estimated cost for one tool | free |
+| `prowl_call_tool` | Invoke any single tool | metered |
+| `prowl_analyze` | Full multi-agent research report in one shot | metered, tier-capped |
+| `prowl_list_playbooks` | The 8 fixed, persona-tuned report shapes | free |
+| `prowl_start_session` / `prowl_session_status` / `prowl_get_session` | Async deep research: kick off, poll, read back | metered |
+| `prowl_generate_artifact` / `prowl_export_report` | Visuals, infographics, audio; Markdown/PDF/PPTX export | metered |
+| `prowl_schedule_create` / `_list` / `_pause` / `_resume` / `_cancel` | Recurring hunts | metered per run |
+| `prowl_get_stats` / `prowl_get_error_feed` / `prowl_reset_session` | Run accounting, failures, state reset | free |
+
+MCP tool args are **flat**, not nested.
+
+Recommended flow: `prowl_search_tools` → `prowl_tool_info` → `prowl_call_tool` for one fact; `prowl_analyze` for a complete strategy report. Pass a stable `session_id` across calls to keep the report cache and conversation memory scoped to one conversation.
+
+Full reference: [https://prowl.chat/mcp/skill.md](https://prowl.chat/mcp/skill.md)
+
+## Tiers
+
+`prowl_analyze` and `prowl_start_session` take a `tier`, which sets the tool budget and the hard provider-cost cap for the run:
+
+| Tier | Use for | Provider cost cap |
+|------|---------|------------------:|
+| `basic` | One question, fast turnaround | $2.50 |
+| `deep` | Full competitive report | $8.00 |
+| `max` | Exhaustive, research-grade | $18.00 |
+
+You are never billed more than the reserved hold.
+
+## Playbooks
+
+Pass `playbook_id` to `prowl_analyze` to force a fixed report shape instead of a dynamically composed one:
+
+`geo-visibility-audit` · `competitor-teardown` · `content-engine` · `local-and-reputation` · `mobile-aso` · `amazon-marketplace` · `idea-validation` · `channel-economics-audit`
+
+Call `prowl_list_playbooks` (free) for what each one covers.
+
+## Verify
+
+1. List MCP tools; confirm `prowl_list_tools`, `prowl_tool_info`, `prowl_call_tool`, `prowl_analyze`.
+2. Run `prowl_list_tools` (free) → 448 tools grouped by category.
+3. Connectivity check (no auth): `curl https://prowl.chat/mcp/health`.
+
+## Billing
+
+- **Subscription pool** (plan renewal, burns at period end) + **extra pool** (top-ups, never expires).
+- Each `prowl_call_tool` response carries a `billing` object (`estimated_cost_usd`, `actual_cost_usd`, `debited`).
+- Insufficient balance blocks the call before it runs — top up at MCP Home.
+
+## The status widget
+
+Installed with the plugin, on by default, and it calls no API — every figure it shows
+was already in a response this agent received.
+
+While a call runs it records it; when the call returns it records the debit the server
+reported. Two things reach the operator without being asked for: a **taskbar/dock
+progress bar** when `prowl_session_status` reports a fraction, and a **one-time
+notice** when a call fails or the wallet blocks one. A repeated failure is said once —
+an agent retrying five times must not produce five notices.
+
+A line at the bottom of the terminal shows the rest: the in-flight call and how long it
+has been running, calls / ok / failed, spend, and the last five tools with their
+verdicts. No plugin manifest can declare a `statusLine`, so the operator wires it once,
+in `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node \"$HOME/.prowl/prowl-statusline.js\"",
+    "refreshInterval": 2
+  }
+}
+```
+
+Copy the script to that stable path, so a plugin update — whose cache directory
+carries the version — cannot break a line the operator wired:
+
+```bash
+mkdir -p ~/.prowl
+cp "$(find ~/.claude/plugins -path '*prowl/statusline/prowl-statusline.js' | head -1)" ~/.prowl/
+```
+
+The copy finds the plugin's library on its own; `PROWL_LIB` overrides the search if
+the plugin lives somewhere unusual. Finding nothing, it prints nothing.
+
+`refreshInterval` matters: status-line updates go quiet while the session waits, which
+is exactly when a Prowl call is in flight and the elapsed segment must keep moving.
+Remove the line again by deleting the `statusLine` field, or with `/statusline clear`.
+
+State lives in `~/.prowl/status/<session_id>.json` beside the token, is pruned after
+seven days, and nothing is ever written to `~/.claude/settings.json` by the plugin.
+
+## When to use
+
+Competitive/market intelligence, SEO/SERP/keyword/backlink research, ad creative & spend research, pricing/funnel analysis, review mining, AI-search (GEO/AEO) visibility, product-idea validation — anything needing real numbers.
+
+## When not to use
+
+Generic coding with no research/data component, or tasks fully answerable from the local codebase.

package/plugins/prowl/statusline/prowl-statusline.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * The bottom line — where a Prowl call is, without asking.
+ *
+ * **Opt-in, and it has to be.** `statusLine` is not a field any plugin manifest can
+ * declare, so a plugin cannot ship one; the operator wires this script themselves,
+ * with one command, and can unwire it with one. That is a worse installation story
+ * than the hooks have and a better one than writing into somebody's settings
+ * uninvited.
+ *
+ * It reads two things and prints one line:
+ *
+ * - the session file, found by the `session_id` in its own payload. The status-line
+ *   reference prescribes exactly this: a pid changes on every invocation and defeats
+ *   any cache keyed by it.
+ * - `cost` and `context_window` from that payload, which exist in **no** hook event.
+ *   This is the only component that can show what the session has spent on the model
+ *   and how much of the window it has eaten, which is why they are shown here and
+ *   nowhere else rather than estimated somewhere convenient.
+ *
+ * It runs on every render, so it does the least possible: read one small JSON file,
+ * format, write. Nothing is computed that was not already recorded, and nothing is
+ * written at all.
+ *
+ * Prints nothing when there is nothing to say. An empty status line is the honest
+ * rendering of "this session has not called Prowl", and better than a line that says
+ * `0 calls` in a repository where the plugin was never used.
+ */
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+/**
+ * Where `lib/` is, from wherever this file was run.
+ *
+ * Beside the plugin it is one directory up. But the documented installation copies
+ * this single file somewhere stable — because a plugin's cache path carries its
+ * version, and a status line wired to it breaks on the next update — and from there
+ * `../lib` is somebody's home directory. So the sibling is tried, then an explicit
+ * override, then the plugin is looked up where plugins live.
+ *
+ * Returns `null` rather than throwing. A status line that cannot find its library
+ * prints nothing, which is the same thing it prints when there is no Prowl call to
+ * report — and far better than a stack trace under the prompt.
+ */
+function resolveLib() {
+  const candidates = [
+    path.join(__dirname, '..', 'lib'),
+    process.env.PROWL_LIB || '',
+  ].filter(Boolean);
+
+  const plugins = path.join(os.homedir(), '.claude', 'plugins');
+  // Bounded, breadth-first, and it stops at the first hit: a full walk of a plugin
+  // cache on every status-line render would be a widget that costs a frame.
+  const roots = [path.join(plugins, 'cache'), path.join(plugins, 'marketplaces')];
+  for (const root of roots) {
+    try {
+      for (const owner of fs.readdirSync(root)) {
+        for (const name of fs.readdirSync(path.join(root, owner))) {
+          if (!/prowl/i.test(name) && !/prowl/i.test(owner)) continue;
+          const dir = path.join(root, owner, name);
+          for (const version of fs.readdirSync(dir)) {
+            candidates.push(path.join(dir, version, 'lib'));
+          }
+        }
+      }
+    } catch (e) { /* no such directory is the normal case on most machines */ }
+  }
+
+  for (const c of candidates) {
+    try {
+      if (fs.existsSync(path.join(c, 'state.js')) && fs.existsSync(path.join(c, 'render.js'))) return c;
+    } catch (e) { /* keep looking */ }
+  }
+  return null;
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => { raw += c; });
+process.stdin.on('end', () => {
+  try {
+    const data = raw.trim().startsWith('{') ? JSON.parse(raw) : {};
+
+    const LIB = resolveLib();
+    if (!LIB) return process.exit(0);
+
+    const state = require(path.join(LIB, 'state.js'));
+    const render = require(path.join(LIB, 'render.js'));
+
+    const line = render.line(state.read(os.homedir(), data.session_id), {
+      now: Date.now(),
+      cost: data.cost,
+      context: data.context_window,
+      // Claude Code sets COLUMNS before running the script; `tput cols` cannot work
+      // here because the output is captured rather than attached to the terminal.
+      columns: Number(process.env.COLUMNS) || null,
+    });
+
+    if (line) process.stdout.write(`${line}\n`);
+  } catch (e) {
+    /* A status line that throws would paint a stack trace under the prompt. */
+  }
+  process.exit(0);
+});

package/plugins/prowl-cli/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "prowl-cli",
+  "description": "Prowl CLI skill: drive the 448-tool Prowl market-intelligence catalog from the shell with @prowl-ai/cli — no MCP server required.",
+  "version": "0.1.1",
+  "author": {
+    "name": "Prowl",
+    "email": "support@prowl.chat",
+    "url": "https://prowl.chat/"
+  },
+  "homepage": "https://prowl.chat/",
+  "repository": "https://github.com/PROWL-AI/prowl-skill",
+  "license": "MIT"
+}

package/plugins/prowl-cli/.codex-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "prowl-cli",
+  "version": "0.1.1",
+  "description": "Prowl CLI skill: drive the 448-tool Prowl market-intelligence catalog from the shell with @prowl-ai/cli — no MCP server required.",
+  "author": {
+    "name": "Prowl",
+    "email": "support@prowl.chat",
+    "url": "https://prowl.chat/"
+  },
+  "homepage": "https://prowl.chat/",
+  "repository": "https://github.com/PROWL-AI/prowl-skill",
+  "license": "MIT",
+  "keywords": [
+    "prowl",
+    "cli",
+    "market-intelligence",
+    "competitive-analysis",
+    "seo",
+    "serp",
+    "ads"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Prowl CLI",
+    "shortDescription": "448 market-intelligence tools from the shell",
+    "longDescription": "Teaches the agent the Prowl command-line client (@prowl-ai/cli): install and key handling, the free catalog commands, metered tool calls, analyze tiers with hard cost caps, playbooks, JSON output and exit codes. Useful wherever a shell is available and no MCP server is configured.",
+    "developerName": "Prowl",
+    "category": "Research",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://prowl.chat/",
+    "privacyPolicyURL": "https://prowl.chat/privacy/",
+    "termsOfServiceURL": "https://prowl.chat/terms/",
+    "defaultPrompt": [
+      "Search the Prowl tool catalog for backlink tools",
+      "Run prowl analyze on a competitor domain",
+      "Check my Prowl wallet balance"
+    ],
+    "brandColor": "#00ff41",
+    "screenshots": []
+  }
+}

package/plugins/prowl-cli/skills/prowl-cli/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: prowl-cli
+description: Drives the Prowl CLI (`@prowl-ai/cli`) — a shell client for Prowl exposing 448 market-intelligence tools (SEO, backlinks, 60+ SERP engines, ads, web scraping, AI) plus the full Prowl research pipeline, billed pay-as-you-go from a USD wallet. Use when a shell is available and market data is needed in a script, a CI job or a one-off command — competitor research, SERP and keyword data, backlink profiles, ad creative research, pricing and demand validation — without configuring an MCP server.
+license: MIT
+compatibility: Requires Node.js 18+, the `@prowl-ai/cli` npm package (installed globally or run via npx) and a Prowl API key; makes network calls to prowl.chat.
+metadata:
+  author: prowl.chat
+  version: "0.1.1"
+---
+
+# Prowl CLI — market intelligence from the shell
+
+`@prowl-ai/cli` is the command-line client for [Prowl](https://prowl.chat): one binary that reaches **448 market-intelligence tools** across 15 providers, plus the Prowl analysis pipeline. Every metered call debits a USD wallet.
+
+Use this skill when a shell is available. Use the sibling `prowl` plugin instead when the agent should call Prowl as MCP tools inside its own tool loop.
+
+## Setup (one time)
+
+Prowl API keys (`prowl_...`) are **billing-bearing** — treat them as secrets and never commit them.
+
+```bash
+npm install -g @prowl-ai/cli
+```
+
+The human generates a key at [prowl.chat](https://prowl.chat) (MCP Home → API keys), then supplies it one of three ways:
+
+```bash
+export PROWL_API_KEY=prowl_...                       # environment
+prowl tools list --key prowl_...                     # per-invocation flag
+mkdir -p ~/.prowl && printf %s 'prowl_...' > ~/.prowl/prowl_mcp_token && chmod 600 ~/.prowl/prowl_mcp_token
+```
+
+Never print the key back to the user, never pass it in a command you echo into a log, and never write it into a repo file.
+
+Requires Node.js >= 18.
+
+## Commands
+
+```
+prowl auth status | login | logout
+prowl tools list                            # 448 tools by category (free)
+prowl tools search "<query>"                # semantic catalog search (free)
+prowl tools info <tool_name>                # input schema + estimated cost (free)
+prowl call <tool_name> --params '<json>'    # invoke one tool (wallet debit)
+prowl analyze "<query>" [--tier basic|deep|max] [--playbook <id>] [--session <id>]
+prowl wallet                                # balance
+prowl version
+```
+
+Global flags: `--json` (one machine-readable JSON document on stdout — always use this when parsing), `--key <k>`, `-h`.
+
+Recommended flow: `tools search` → `tools info` (check the cost) → `call`. Reach for `analyze` when the goal is a full report rather than one data point. Pass a stable `--session <id>` across consecutive `analyze` calls to keep the report cache and conversation history scoped to one investigation.
+
+## Tiers and cost control
+
+`analyze` defaults to `--tier basic`. Each tier holds a hard provider-cost cap for the run — billing never exceeds the reserved hold.
+
+| Tier | Use for | Cap |
+|------|---------|----:|
+| `basic` | one question, fast turnaround | $2.50 |
+| `deep` | full competitive report | $8.00 |
+| `max` | exhaustive, research-grade | $18.00 |
+
+Check `prowl tools info <tool>` before a `call` in a loop, and `prowl wallet` before a batch. Confirm with the human before running `--tier max` or a batch that could exceed a few dollars.
+
+## Playbooks
+
+`--playbook <id>` forces a fixed, persona-tuned report shape:
+
+`geo-visibility-audit` · `competitor-teardown` · `content-engine` · `local-and-reputation` · `mobile-aso` · `amazon-marketplace` · `idea-validation` · `channel-economics-audit`
+
+## Exit codes
+
+`0` ok · `1` runtime/tool error · `2` usage · `3` auth (missing or invalid key) · `4` insufficient balance · `5` network/timeout.
+
+Handle them: `3` means ask the human for a key, `4` means stop and report the balance rather than retrying, `5` is the only one worth a retry.
+
+## Examples
+
+```bash
+prowl tools search "backlinks"
+prowl tools info majestic_get_back_link_data
+prowl call extract_domain_from_url --params '{"url":"https://stripe.com/pricing"}'
+prowl analyze "competitors of stripe.com" --tier basic --json
+prowl analyze "is there demand for an AI receipt scanner" --playbook idea-validation --tier deep
+```
+
+## When to use
+
+Competitor and market research, SEO/SERP/keyword data, backlink profiles, ad creative and spend research, pricing and demand validation — from a script, a CI job, or a shell one-liner.
+
+## When not to use
+
+Tasks answerable from the local codebase, or sessions where the Prowl MCP server is already configured — there the `prowl` plugin's tools are the better path.
+
+Full tool reference: [https://prowl.chat/mcp/skill.md](https://prowl.chat/mcp/skill.md)