pp-botsee

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/marketing/botsee/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# BotSee — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `botsee-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install botsee --cli-only
   ```
2. Verify: `botsee-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/marketing/botsee/cmd/botsee-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Reach for this CLI when an agent or pipeline needs structured BotSee data without burning credits on repeat reads. Best for: running a fresh AI-visibility audit (`ai-visibility-audit <url>` is the headline), inspecting an existing site's setup (`site-config`), generating recommendations from a completed analysis, or aggregating cited sources across multiple sites for a portfolio view. Not the right tool for hosted dashboard UI use — that's `app.botsee.io`.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Flagship workflow
- **`ai-visibility-audit`** — One command runs the full BotSee audit: idempotent on existing sites, bootstraps customer types and personas and questions if missing, then runs analysis across every LLM and prints a structured visibility report.

  _This is THE command. Reach for it when an agent or user says 'audit my AI visibility' or 'check how AI sees example.com' — it handles the full lifecycle._

  ```bash
  botsee-pp-cli ai-visibility-audit example.com --types 2 --personas 2 --questions 5 --watch --agent
  ```
- **`recommendations`** — Generate next-step recommendations from an analysis — promoted to top-level so agents can discover it without descending into the analysis subcommand tree.

  _Use after an analysis to get LLM-generated action items without re-spending if you already pulled them once._

  ```bash
  botsee-pp-cli recommendations $ANALYSIS_UUID --agent
  ```

### Workflow plumbing
- **`site-config`** — Print the full customer-types -> personas -> questions tree for a site, with UUIDs and the actual edit commands users can copy-paste to add, update, or remove any node.

  _Reach for this when a user asks 'what is set up for this site' or 'show me my BotSee config' — it surfaces every UUID needed for follow-up edits._

  ```bash
  botsee-pp-cli site-config --site $SITE_UUID --agent
  ```
- **`sites-summary`** — Aggregate cited sources across every synced site, grouped by domain, with citation count, distinct sites citing each domain, and first-seen timestamp.

  _Use for multi-site users and agencies who need the cross-portfolio answer 'which sources keep getting cited everywhere' — impossible without local aggregation._

  ```bash
  botsee-pp-cli sites-summary --agent --select domain,citation_count,distinct_sites_citing,first_seen
  ```

## Command Reference

**account** — Manage account

- `botsee-pp-cli account` — Returns account details including company name, site count, and owner information.

**analysis** — Manage analysis

- `botsee-pp-cli analysis get` — Returns analysis details including status. Poll this endpoint until status is 'completed' or 'failed'.
- `botsee-pp-cli analysis run` — Starts an analysis run. This is asynchronous - poll GET /api/v1/analysis/:uuid for status. Returns 202 Accepted.

**api-keys** — Manage api keys

- `botsee-pp-cli api-keys create` — Creates a new API key. The raw key is returned only once in the response body — store it immediately.
- `botsee-pp-cli api-keys delete` — Revokes an API key. You cannot revoke the key being used to make this request — use rotate or another key.
- `botsee-pp-cli api-keys list` — Lists all API keys for the organization (raw key never returned).
- `botsee-pp-cli api-keys reset` — Exchanges a one-time reset token (from email) for a fresh API key.

**billing** — Manage billing

- `botsee-pp-cli billing get-settings` — Returns the organization's billing settings and current credit balance.
- `botsee-pp-cli billing topoff-via-x402` — Discovery call without payment headers returns 402 and does not require auth.
- `botsee-pp-cli billing update-settings` — Updates the organization's monthly spend limit. Other settings are read-only via this endpoint.

**botsee-auth** — Manage botsee auth

- `botsee-pp-cli botsee-auth` — Validates the API key and returns organization info and credit balance.

**customer-types** — Manage customer types

- `botsee-pp-cli customer-types delete` — Archives a customer type. Returns 204 No Content on success.
- `botsee-pp-cli customer-types get` — Returns a customer type with its personas.
- `botsee-pp-cli customer-types update` — Updates a customer type. Only include fields you want to change.

**personas** — Manage personas

- `botsee-pp-cli personas delete` — Archives a persona. Returns 204 No Content on success.
- `botsee-pp-cli personas get` — Returns a persona with its questions.
- `botsee-pp-cli personas update` — Updates a persona. Only include fields you want to change.

**pricing** — Manage pricing

- `botsee-pp-cli pricing` — Returns the credit cost for each chargeable operation.

**questions** — Manage questions

- `botsee-pp-cli questions delete` — Deletes a question. Returns 204 No Content on success.
- `botsee-pp-cli questions update` — Updates a question. Only include fields you want to change.

**rate-limits** — Manage rate limits

- `botsee-pp-cli rate-limits` — Returns the caller's current rate-limit state without consuming additional budget.

**signup** — Manage signup

- `botsee-pp-cli signup via-cc` — Creates a credit-card signup token. USDC signups must use `/api/v1/signup/usdc`.
- `botsee-pp-cli signup via-usdc-token` — Creates a USDC signup token. Use `no_email: true` for autonomous agent flows (no setup_url returned).

**sites** — Manage sites

- `botsee-pp-cli sites create` — Creates a new site. Auto-generates product_name and value_proposition from URL if not provided (5 credits).
- `botsee-pp-cli sites delete` — Archives a site. Returns 204 No Content on success.
- `botsee-pp-cli sites get` — Returns a site with its customer types and persona counts.
- `botsee-pp-cli sites list` — Returns a paginated list of sites for the organization.

**usage** — Manage usage

- `botsee-pp-cli usage by-key` — Returns credit usage breakdown per API key.
- `botsee-pp-cli usage get` — Returns credit balance, auto-charge settings, and paginated transaction history.

**webhooks** — Manage webhooks

- `botsee-pp-cli webhooks create` — Registers a webhook URL. Returns the webhook with its signing secret (shown only once).
- `botsee-pp-cli webhooks delete` — Deletes a webhook. Returns 204 No Content on success.
- `botsee-pp-cli webhooks list` — Lists all registered webhooks for the organization.
- `botsee-pp-cli webhooks list-events` — Returns the catalog of event types this API can emit, with JSON Schemas per event.


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
botsee-pp-cli which "<capa