Plausible Analytics

Query and analyze website analytics from Plausible Analytics. Use when you need to check real-time visitors, get page views and visitor statistics for a time...

Security Scan

The skill's code, instructions, and required environment variables are coherent with its stated purpose (querying Plausible Analytics) and do not request unrelated access.

Purpose & Capability

Name/description match the behavior: the skill needs a Plausible API key and runs Node scripts that call plausible.io endpoints to fetch stats, realtime visitors, and breakdowns. There are no unexpected credentials, binaries, or config paths requested.

Instruction Scope

SKILL.md and the three scripts only instruct running Node scripts that call Plausible API endpoints. The scripts read only the declared env vars (PLAUSIBLE_API_KEY and optional PLAUSIBLE_SITE_ID) and CLI arguments; they don't access other system files, services, or external endpoints beyond plausible.io.

Install Mechanism

No install spec; this is instruction+script based. All included code is small, readable, and makes HTTPS calls to plausible.io. There are no downloads from arbitrary URLs, no archive extraction, and no package installation specified by the skill itself.

Credentials

Only PLAUSIBLE_API_KEY is required (PLAUSIBLE_SITE_ID optional). That is appropriate and proportionate for a Plausible Analytics integration. No unrelated secrets or broad system credentials are requested.

Persistence & Privilege

always is false, the skill does not request permanent/system-level presence, and the scripts do not modify other skills or system-wide configuration.

Assessment

This skill appears to do exactly what it claims: run Node scripts that query plausible.io using your PLAUSIBLE_API_KEY. Before installing, ensure you: (1) only provide a Plausible API key you trust and be careful not to paste it into chat; (2) run the scripts in an environment with Node (Node 18+ recommended for global fetch) and isolate credentials (use a scoped/limited key if Plausible supports it); (3) review/rotate the API key if you later uninstall or suspect misuse; and (4) verify network egress to plausible.io is acceptable in your environment. The code is small and readable, but treat any API key as sensitive.

Overview

Retrieve and analyze website analytics data from Plausible Analytics API. Supports real-time visitor tracking, historical statistics, traffic source analysis, and detailed breakdowns by page, source, or country.

Quick Start

All scripts require PLAUSIBLE_API_KEY environment variable. Site ID can be provided via PLAUSIBLE_SITE_ID environment variable or as a script argument.

# Set API key
export PLAUSIBLE_API_KEY="your-api-key"

# Quick example: Get today's stats
node scripts/stats.mjs example.com --period day

Real-Time Visitors

Check how many people are currently viewing your site:

node scripts/realtime.mjs <site-id>

Example output:

{
  "visitors": 42
}

Statistics

Get page views, visitors, bounce rate, and visit duration for a time period:

node scripts/stats.mjs <site-id> [--period day|7d|30d|month|6mo|12mo] [--date YYYY-MM-DD]

Parameters:

• period - Time period to query (default: day)
• date - Specific date for the period (default: today)

Example:

# Get today's stats
node scripts/stats.mjs example.com

# Get last 7 days
node scripts/stats.mjs example.com --period 7d

# Get stats for a specific month
node scripts/stats.mjs example.com --period month --date 2026-02-01

Example output:

{
  "results": {
    "visitors": {
      "value": 1234
    },
    "pageviews": {
      "value": 5678
    },
    "bounce_rate": {
      "value": 45
    },
    "visit_duration": {
      "value": 180
    }
  }
}

Detailed Breakdown

Analyze traffic by specific dimensions (pages, sources, countries, etc.):

node scripts/breakdown.mjs <site-id> <property> [--period day|7d|30d] [--limit N]

Properties:

• visit:source - Traffic sources (Google, Twitter, direct, etc.)
• visit:referrer - Referring URLs
• visit:utm_medium / visit:utm_source / visit:utm_campaign - UTM parameters
• visit:device - Desktop vs Mobile
• visit:browser - Browser breakdown
• visit:os - Operating system
• visit:country - Countries
• event:page - Top pages

Example:

# Top 10 pages in the last 7 days
node scripts/breakdown.mjs example.com event:page --period 7d --limit 10

# Traffic sources today
node scripts/breakdown.mjs example.com visit:source

# Countries in the last 30 days
node scripts/breakdown.mjs example.com visit:country --period 30d

Example output:

{
  "results": [
    {
      "page": "/",
      "visitors": 542,
      "pageviews": 1024
    },
    {
      "page": "/about",
      "visitors": 123,
      "pageviews": 145
    }
  ]
}

Environment Variables

• PLAUSIBLE_API_KEY (required) - Your Plausible API key
• PLAUSIBLE_SITE_ID (optional) - Default site ID to use

Resources

scripts/

• stats.mjs - Aggregate statistics for a time period
• realtime.mjs - Current visitor count
• breakdown.mjs - Detailed breakdown by dimension