posthog-analytics

# PostHog Analytics Skill

Automate PostHog dashboard creation, sync, update, and export via API.

## Prerequisites

### Required Tools
- `curl` - HTTP client (pre-installed on macOS/Linux)
- `jq` - JSON processor: `brew install jq` or `apt install jq`
- `bash` - Shell (the script is bash)

### PostHog API Key

1. Go to [PostHog Settings → Personal API Keys](https://us.posthog.com/settings/user-api-keys)
2. Create a new key with read/write access
3. Export it:

```bash
export POSTHOG_PERSONAL_API_KEY=phx_xxx
```

**Note**: The API key determines your organization and project. The script uses `@current` project context (your default project).

### Verify Setup

```bash
# Test your API key - should return your project info
curl -s -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
  "https://us.i.posthog.com/api/projects/@current/" | jq '{id, name}'
```

Expected output:
```json
{
  "id": 209268,
  "name": "Default project"
}
```

If you get an error, check your API key is correct and has proper permissions.


## Quick Start: Blog Analytics Example

### Step 1: Write Your Config

Create `blog_dashboard.json`:

```json
{
  "name": "Blog Analytics",
  "description": "Track blog performance and reader engagement",
  "filter": {"key": "source", "value": "blog"},
  "dashboard_id": null,
  "insights": [
    {"name": "Blog Pageviews (Total)", "type": "pageviews_total"},
    {"name": "Unique Blog Readers", "type": "unique_users"},
    {"name": "Blog Traffic Trend", "type": "traffic_trend"},
    {"name": "Top Blog Posts", "type": "top_pages"}
  ]
}
```

**Note**: Set `dashboard_id: null` for new dashboards.

### Step 2: Create Dashboard

```bash
./scripts/posthog_sync.sh create blog_dashboard.json
```

**Output**:
```
Creating dashboard: Blog Analytics
Dashboard created: ID 1166599
Creating insight: Blog Pageviews (Total)
{id: 6520531, name: "Blog Pageviews (Total)"}
...
Dashboard URL: https://us.posthog.com/project/209268/dashboard/1166599
```

The script:
- Creates a new dashboard in your PostHog project
- Returns **dashboard_id** (e.g., `1166599`) and **project_id** (e.g., `209268`) in the URL
- **Automatically updates** your config file with the `dashboard_id`

### Step 3: Add New Insights (Sync)

Edit config to add new insights, then:

```bash
./scripts/posthog_sync.sh sync blog_dashboard.json
```

Only creates NEW insights. Existing ones (matched by name) are **skipped**.

### Step 4: Update Existing Insights

Changed your filter? Edit config, then:

```bash
./scripts/posthog_sync.sh update blog_dashboard.json
```

Updates ALL insights with current config settings. Use when changing filters.

### Step 5: Export Existing Dashboard

```bash
./scripts/posthog_sync.sh export 1166599 > exported_dashboard.json
```

## Config Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Dashboard name |
| `description` | No | Dashboard description |
| `filter` | No* | Event property filter: `{"key": "source", "value": "blog"}` |
| `domain_filter` | No* | URL filter fallback: `"blog.sylph.ai"` |
| `dashboard_id` | No | Set to `null` for create, or existing ID for sync/update |
| `insights` | Yes | Array of insight objects |

*At least one filter recommended. `filter` takes precedence over `domain_filter`.

### Insight Types

| Type | Display | Description |
|------|---------|-------------|
| `pageviews_total` | BoldNumber | Total pageview count |
| `unique_users` | BoldNumber | Unique visitors (DAU) |
| `traffic_trend` | LineGraph | Traffic over time |
| `top_pages` | Table | Top pages breakdown |

### Optional Insight Fields

| Field | Default | Options |
|-------|---------|---------|
| `math` | `total` | `total`, `dau`, `weekly_active`, `monthly_active` |
| `display` | Auto | `BoldNumber`, `ActionsLineGraph`, `ActionsTable` |
| `date_range` | `-30d` | `-7d`, `-30d`, `-90d`, etc. |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `POSTHOG_PERSONAL_API_KEY` | Yes | - | Your API key (determines org/project) |
| `POSTHOG_HOST` | No | us.i.posthog.com | API host (EU: eu.i.posthog.com) |
| `POSTHOG_UI_HOST` | No | us.posthog.com | UI host for dashboard URLs |

## Files

- `scripts/posthog_sync.sh` - CLI script (create/sync/update/export)
- `examples/blog_dashboard.json` - Example config

## References

- [PostHog API Docs](https://posthog.com/docs/api)
- [Personal API Keys](https://posthog.com/docs/api/overview#personal-api-keys)