PromptWatch CLI

Unofficial CLI that wraps the PromptWatch API

Access the PromptWatch API via CLI commands or as a Python tool for AI agents. Monitor AI model responses, track brand visibility across LLMs, analyze citations, and measure share of voice.

Two Ways to Use

1. CLI (Terminal/Scripts)

Install globally and use via command line:

npm install -g promptwatch-cli
promptwatch models list

2. Python API Tool (AI Agents)

Install the skill into your AI agent project (no npm required):

npm install -g promptwatch-cli
promptwatch add-skill ~/my-agent-project

This installs a standalone Python API client to .claude/skills/promptwatch/tools/promptwatch_api.py that works without the CLI.

Installation

For CLI Usage

npm install -g promptwatch-cli

For AI Agent Integration

# Install CLI globally
npm install -g promptwatch-cli

# Add skill to your AI agent project
promptwatch add-skill ~/your-project
# Creates: ~/your-project/.claude/skills/promptwatch/

Quick Start (CLI)

1. Set Your API Key

Option A: Use command-line flag (no config needed)

promptwatch --api-key YOUR_API_KEY models list

Option B: Save to config

promptwatch config set apiKey YOUR_API_KEY

Option C: Use .env file

# Edit .env and add your key
PROMPTWATCH_API_KEY=your_key_here

2. Validate Authentication

promptwatch auth validate

Add Skill to AI Agent Projects

Install the PromptWatch skill (with Python API tool) to any AI agent project:

promptwatch add-skill ~/my-agent-project

What it installs:

~/my-agent-project/.claude/skills/promptwatch/
├── SKILL.md                    # Complete documentation
├── references/                 # Detailed API endpoint docs
│   ├── monitors.md
│   ├── prompts.md
│   ├── analytics.md
│   └── ...
└── tools/
    └── promptwatch_api.py      # Standalone Python client

Requirements:

• No npm installation needed in target project
• Set PROMPTWATCH_API_KEY environment variable
• Python 3.6+ (uses only standard library)

CLI Usage

All commands output JSON for easy parsing by AI agents.

Authentication

promptwatch auth validate

Models

# List all models
promptwatch models list

# Include deprecated models
promptwatch models list --include-deprecated

Monitors

# List monitors
promptwatch monitors list --start-date 2024-01-01 --end-date 2024-01-31

# Get specific monitor
promptwatch monitors get MONITOR_ID

# Create monitor
promptwatch monitors create \
  --name "My Monitor" \
  --description "Monitor description" \
  --models "openai_gpt-4o,google_gemini-pro" \
  --language en-US \
  --country US

# Update monitor
promptwatch monitors update MONITOR_ID --name "Updated Name"

# Delete monitor
promptwatch monitors delete MONITOR_ID

Prompts

# List prompts
promptwatch prompts list --page 1 --size 20 --monitor MONITOR_ID

# Get prompt
promptwatch prompts get PROMPT_ID

# Create prompt
promptwatch prompts create \
  --prompt "What is AI?" \
  --monitor MONITOR_ID \
  --type ORGANIC

# Update prompt
promptwatch prompts update PROMPT_ID --type BRAND_SPECIFIC

# Delete prompt
promptwatch prompts delete PROMPT_ID

# Bulk operations
promptwatch prompts bulk-create \
  --monitor MONITOR_ID \
  --prompts '[{"prompt":"Q1"},{"prompt":"Q2"}]'

promptwatch prompts bulk-delete --ids ID1,ID2,ID3
promptwatch prompts activate --ids ID1,ID2
promptwatch prompts deactivate --ids ID1,ID2

# Rerun prompt
promptwatch prompts rerun PROMPT_ID

# Add tags
promptwatch prompts add-tags PROMPT_ID --tags tag1,tag2

Tags

# List tags
promptwatch tags list --query "search"

# Create tags
promptwatch tags create --names tag1,tag2,tag3

# Update tag
promptwatch tags update TAG_ID --name "New Name"

# Delete tag
promptwatch tags delete TAG_ID

Personas

# List personas
promptwatch personas list

# Get persona
promptwatch personas get PERSONA_ID

# Create persona
promptwatch personas create \
  --name "Tech Professional" \
  --description "Software engineer" \
  --age-range "25-34" \
  --education "Bachelor's"

# Update persona
promptwatch personas update PERSONA_ID --name "Updated Name"

# Delete persona
promptwatch personas delete PERSONA_ID

Brands

# List brands
promptwatch brands list --relation COMPETITOR

# Create brand
promptwatch brands create \
  --name "Brand Name" \
  --relation COMPETITOR \
  --url "https://example.com"

# Update brand
promptwatch brands update BRAND_ID --relation PARTNER

Projects (Org-level keys only)

# List projects
promptwatch projects list

# Create project
promptwatch projects create \
  --name "New Project" \
  --website "https://example.com" \
  --country US \
  --language en

Analytics

# Visibility time series
promptwatch analytics visibility \
  --range day \
  --start-date 2024-01-01 \
  --end-date 2024-01-31 \
  --models openai_gpt-4o

# Competitor heatmap
promptwatch analytics heatmap \
  --start-date 2024-01-01 \
  --limit 50 \
  --exclude-self

# Sentiment
promptwatch analytics sentiment --range week

# Visitors
promptwatch analytics visitors-total --start-date 2024-01-01
promptwatch analytics visitors-trend

# Crawlers
promptwatch analytics crawlers-trend
promptwatch analytics crawlers-pages

# Brands visibility
promptwatch analytics brands-visibility --range daily --limit 20

Citations

# List citations
promptwatch citations list --start-date 2024-01-01 --limit 50

# Self frequency
promptwatch citations self-frequency --range DAILY

# Domains over time
promptwatch citations domains-over-time --range WEEKLY --domain-limit 10

# Rank analysis
promptwatch citations rank-analysis --range MONTHLY

# Top pages
promptwatch citations top-pages --limit 100

# LLM sources
promptwatch citations llm-sources --limit 10

# Domains by LLM
promptwatch citations domains-by-llm --limit 20

Share of Voice

# Time series
promptwatch share-of-voice time-series --range day

# Comparison
promptwatch share-of-voice comparison \
  --start-date 2024-01-01 \
  --end-date 2024-01-31

Responses

# List responses
promptwatch responses list \
  --page 1 \
  --size 20 \
  --sentiment POSITIVE \
  --mentioned-brand

# Get response
promptwatch responses get RESPONSE_ID

# Summary
promptwatch responses summary --start-date 2024-01-01

# Mentions time series
promptwatch responses mentions --range week

# Competitors
promptwatch responses competitors

# Sentiment distribution
promptwatch responses sentiment-distribution

# Sentiment time series
promptwatch responses sentiment-time-series

Environment Variables

PROMPTWATCH_API_KEY      # Your API key (required)
PROMPTWATCH_BASE_URL     # Base URL (default: https://server.promptwatch.com)

Python API Tool (for AI Agents)

After running promptwatch add-skill <folder>, use the standalone Python client:

Setup

# Set API key environment variable
export PROMPTWATCH_API_KEY=your_key_here

Usage

# Located at: .claude/skills/promptwatch/tools/promptwatch_api.py
from promptwatch_api import PromptWatchAPI

# Initialize (reads from PROMPTWATCH_API_KEY env var)
api = PromptWatchAPI()

# Use any API method
models = api.get_models()
monitors = api.list_monitors()
prompt = api.create_prompt("What is AI?", monitor_id)
visibility = api.get_visibility(range="day")

All CLI commands have equivalent Python methods. See .claude/skills/promptwatch/SKILL.md for complete documentation.

For AI Agents (CLI Output)

All CLI commands output JSON to stdout, making it easy to parse:

# Get models and parse with jq
promptwatch models list | jq '.[] | select(.deprecated == false)'

# Get monitor metrics
promptwatch monitors list --start-date 2024-01-01 | jq '.[0].responseCount'

# Create prompt and get ID
promptwatch prompts create --prompt "Test" --monitor ID | jq '.id'

Rate Limits

• Limit: 1,000 requests per minute per IP
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• Retry: Automatic retry with backoff on 429 errors

Caching

• Models: 24 hours
• Monitors: 1 hour
• Analytics: 5 minutes

API Coverage

✅ 63 endpoints across V2 API:

• Authentication (1)
• Models (1)
• Monitors (5 CRUD)
• Prompts (11 including bulk)
• Tags (4 CRUD)
• Personas (5 CRUD)
• Brands (3)
• Projects (2)
• Analytics (11)
• Citations (7)
• Share of Voice (2)
• Responses (7)

License

MIT