Marketing

Botsee

pp-botsee

Have your agents measure and improve your brand's AI Visibility with botsee.io. API-first, agent-native.

Printed by @grahac

Install

npx — recommended

npx -y @mvanhorn/printing-press-library install botsee

Installs the CLI binary and the agent skill (Claude Code, Codex, Cursor, Gemini CLI, Copilot, and more). Add --cli-only or --skill-only for one half. Requires Node.

Hermes

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-botsee --force

From the Hermes CLI. Inside a chat session use /skills install with the same path.

OpenClaw

Install the pp-botsee skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-botsee. The skill defines how its required CLI can be installed.

Paste this to your OpenClaw agent — the skill describes how to install its CLI.

Claude Desktop

This CLI ships an MCPB bundle. Download the latest release .mcpb and double-click it — Claude Desktop walks you through the install.

View source on GitHub →

Have your agents measure and improve your brand's AI Visibility with botsee.io. Run audits across every major LLM, see what's missing, then get specific recommendations and ready-to-publish content to close the gap. API-first, agent-native

BotSee is the API-first GEO platform; this CLI is the API-first front door. The flagship ai-visibility-audit <url> mirrors the proven Python create-site+analyze flow as a single idempotent Go command. The other 64 commands cover the entire BotSee surface (CRUD on sites/customer-types/personas/questions, the full analysis lifecycle, recommendations, blog content, billing, signup including USDC/x402, webhooks, api-key rotation, usage) plus framework commands (sync/search/sql/doctor) over a local SQLite cache.

Printed by @grahac (grahac).

Authentication

BotSee uses Bearer tokens prefixed bts_live_. Set BOTSEE_API_KEY in your environment and the CLI threads it into every authenticated call. Manage keys with api-keys list / create / rotate / reset / delete — reset consumes a one-time token emailed to the account holder if the key was lost. The CLI never logs key values.

Quick Start

# Verify auth, reachability, and remaining rate-limit budget
botsee-pp-cli doctor


# Flagship — bootstrap a new site, run analysis, print results. Idempotent: a second run on the same domain reuses the existing site and just runs a fresh analysis.
botsee-pp-cli ai-visibility-audit example.com --types 2 --personas 2 --questions 5 --watch


# Inspect the customer-types / personas / questions tree for the site (with copy-paste edit commands)
botsee-pp-cli site-config --site $SITE_UUID --agent


# Generate next-step recommendations from the analysis (cached locally)
botsee-pp-cli recommendations $ANALYSIS_UUID --agent


# Cross-site cited-source rollup — useful once you've audited multiple domains
botsee-pp-cli sites-summary --agent

Unique Features

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.
```
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.
```
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.
```
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.
```
botsee-pp-cli sites-summary --agent --select domain,citation_count,distinct_sites_citing,first_seen
```

Usage

Run botsee-pp-cli --help for the full command reference and flag list.

Commands

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. Public endpoint — no Bearer auth required, the token authenticates the request.

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. Final paid retry requires API key (Authorization, x-api-key, or api_key query param) and supports both payment and payment-signature headers. Method-compatible with POST, PUT, PATCH, and DELETE.
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. Analysis costs are estimates; the actual debit is computed from real LLM usage at the documented multiplier after the run completes.

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. Useful for agents that want to back off proactively before hitting 429.

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. Use this to self-discover available events programmatically without parsing the full OpenAPI doc.

Output Formats

# Human-readable table (default in terminal, JSON when piped)
botsee-pp-cli account

# JSON for scripting and agents
botsee-pp-cli account --json

# Filter to specific fields
botsee-pp-cli account --json --select id,name,status

# Dry run — show the request without sending
botsee-pp-cli account --dry-run

# Agent mode — JSON + compact + no prompts in one flag
botsee-pp-cli account --agent

Agent Usage

This CLI is designed for AI agent consumption:

Non-interactive - never prompts, every input is a flag
Pipeable - --json output to stdout, errors to stderr
Filterable - --select id,name returns only fields you need
Previewable - --dry-run shows the request without sending
Explicit retries - add --idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
Confirmable - --yes for explicit confirmation of destructive actions
Piped input - write commands can accept structured input when their help lists --stdin
Offline-friendly - sync/search commands can use the local SQLite store when available
Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

botsee-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/botsee-pp-cli/config.toml

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name	Kind	Required	Description
`BOTSEE_API_KEY`	per_call	Yes	Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

Run botsee-pp-cli doctor to check credentials
Verify the environment variable is set: echo $BOTSEE_API_KEY Not found errors (exit code 3)
Check the resource ID is correct
Run the list command to see available items

API-specific

doctor fails with 401 Unauthorized — Confirm BOTSEE_API_KEY is set and starts with bts_live_. Rotate via botsee-pp-cli api-keys rotate <id> if compromised.
ai-visibility-audit says site exists but I expected a fresh setup — Default behavior is idempotent: reuses the existing site by normalized domain match. Pass --regenerate to force LLM re-generation of customer types and personas, or use a different domain.
Cost estimate looks too high or too low — The estimator reads cost_multiplier from the live /pricing endpoint; if BotSee adjusts it, your estimates adjust automatically. Use --estimate-only to preview without spending.
429 Too Many Requests during sync — The 600 req/min budget is per key. Add --max-pages 5 to sync, or check the X-RateLimit-Reset header via rate-limits get.
USDC top-up via x402 hangs — x402 challenges return a 402 with payment requirements; the CLI prints the payTo address. Pay from a wallet (Pinch, Coinbase CDP), then re-run with --payment <proof>.

Generated by CLI Printing Press