npm package: @llmpulse/cli
Description: CLI client for the LLM Pulse AI visibility analytics API
Latest version: 0.1.0

# @llmpulse/cli

CLI client for the [LLM Pulse](https://llmpulse.ai) AI visibility analytics API.

## Installation

```bash
npm install -g @llmpulse/cli
```

## Quick Start

```bash
# Configure your API key
llmpulse config set api_key llmpulse_your_key_here

# Check connectivity
llmpulse ping

# List your projects
llmpulse dimensions projects list

# Set a default project
llmpulse config set default_project_id 44

# Get weekly mentions timeseries
llmpulse metrics timeseries --metrics mentions --granularity week --range 30

# Get share of voice
llmpulse metrics sov --range 30

# List prompts as a table
llmpulse dimensions prompts -f table

# Export citations as CSV
llmpulse dimensions citations -f csv > citations.csv

# Fetch all mentions (auto-paginate)
llmpulse dimensions mentions --all -f csv > all-mentions.csv
```

## Commands

| Command | Description |
|---------|-------------|
| `config set/get/show` | Manage CLI configuration |
| `ping` | Check API connectivity |
| `dimensions projects` | List/get projects |
| `dimensions competitors` | List/get competitors |
| `dimensions collections` | List collections/tags |
| `dimensions models` | List AI models |
| `dimensions locales` | List countries and languages |
| `dimensions prompts` | List prompts |
| `dimensions executions` | List prompt executions |
| `dimensions sources` | List cited sources |
| `dimensions mentions` | List brand mentions |
| `dimensions citations` | List brand citations |
| `dimensions competitor-mentions` | List competitor mentions |
| `dimensions competitor-citations` | List competitor citations |
| `dimensions all-mentions` | All mentions (brand + competitor) |
| `dimensions all-citations` | All citations (brand + competitor) |
| `dimensions sentiments` | Sentiment categories |
| `metrics timeseries` | Time series metrics |
| `metrics summary` | Aggregated metrics summary |
| `metrics prompt-summary` | Per-prompt metrics |
| `metrics sov` | Share of voice |
| `metrics top-sources` | Top cited domains |
| `answers list` | List AI responses |
| `answers get <id>` | Get detailed response |
| `sentiments list` | List sentiment records |

## Global Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--api-key` | `-k` | Override API key |
| `--base-url` | | Override base URL |
| `--project-id` | `-p` | Override default project |
| `--format` | `-f` | Output: `json` (default), `table`, `csv` |
| `--page` | | Page number |
| `--per-page` | | Items per page (max 100) |
| `--all` | | Auto-paginate all results |
| `--verbose` | `-v` | Show request details |

## Configuration

Configuration is stored in `~/.llmpulse/config.json`. Values can be overridden with environment variables or CLI flags.

**Priority:** CLI flag > environment variable > config file > default

| Config Key | Environment Variable | Default |
|------------|---------------------|---------|
| `api_key` | `LLMPULSE_API_KEY` | — |
| `base_url` | `LLMPULSE_BASE_URL` | `https://api.llmpulse.ai/api/v1` |
| `default_project_id` | `LLMPULSE_PROJECT_ID` | — |

## Output Formats

- **JSON** (default): Pretty-printed on TTY, compact when piped (for `jq`)
- **Table**: Auto-sized columns, pagination info on stderr
- **CSV**: Standard CSV with proper escaping

```bash
# Pipe JSON to jq
llmpulse metrics summary --metrics mentions,visibility | jq '.series'

# Export to CSV file
llmpulse dimensions prompts --all -f csv > prompts.csv
```

## Requirements

- Node.js >= 18
- LLM Pulse API key (Scale plan or above)