plausible_skill

Overview

This skill provides a shell-focused interface to the Plausible Analytics API for querying website statistics and managing sites. It helps retrieve visitors, pageviews, traffic sources, geographic and device breakdowns, and manage sites, goals, and shared links. Use it to automate analytics reporting and site provisioning with curl-based commands.

How this skill works

Commands create JSON requests written to a temporary file and call Plausible endpoints with curl using an API key stored in environment variables. The skill supports the Stats API (v2) for queries with metrics, dimensions, filters, date ranges and pagination, and the Sites API (v1) for listing, creating, deleting sites and managing goals and shared links. Use bash -c when piping to avoid environment variable clearing with pipes.

When to use it

• Run quick visitor, pageview, or time series queries for a site from a CI job or shell script.
• Generate top pages, geographic or device breakdowns for a reporting dashboard.
• Filter analytics by page path, UTM campaign, or custom dimensions for campaign analysis.
• Provision new sites, create goals, or create shared dashboard links programmatically.
• Automate periodic exports within Plausible rate limits (600 requests/hour).

Best practices

• Store PLAUSIBLE_API_KEY and PLAUSIBLE_SITE_ID in environment variables and never commit them to source control.
• Write JSON payloads to a temporary file and use bash -c 'curl ...' when piping to jq to preserve env variables.
• Limit pagination and use date ranges to reduce payload size and stay within rate limits.
• Create goals before querying conversion_rate metrics to ensure meaningful results.
• Use dimensions and filters to narrow queries and reduce post-processing work.

Example use cases

• Daily CI job that posts yesterday's visitors and top 10 pages to a Slack channel.
• Marketing report breaking down visitors by UTM source and campaign for the last 30 days.
• Geo heatmap generation using visit:country_name and visit:city_name for the past month.
• Automated site onboarding that creates a new site, configures timezone, and creates a signup goal.
• Ad-hoc debugging: filter events by page path to verify analytics tagging on a /blog section.