Skill: kryzl19/plausible-analytics-agent (version 1.0.0)

--- name: plausible-analytics description: Track pageviews and custom events via the Plausible Events API, and query stats (top pages, top sources, countries, realtime visitors). Use when you need to send analytics events or fetch analytics data from a self-hosted or plausible.io site. metadata: { "openclaw": { "emoji": "📊", "requires": { "env": ["PLAUSIBLE_SITE_DOMAIN", "PLAUSIBLE_API_KEY"], }, }, } --- # Plausible Analytics Track events and query stats from Plausible Analytics (self-hosted or plausible.io). ## Configuration Set these environment variables before use: ```bash # Your site domain (e.g. example.com) export PLAUSIBLE_SITE_DOMAIN="example.com" # Your Plausible API key (for stats endpoints) export PLAUSIBLE_API_KEY="your-api-key" # Plausible base URL (default: https://plausible.io for hosted) # For self-hosted, set to your instance URL export PLAUSIBLE_BASE_URL="https://plausible.io" ``` ## Track Pageview ```bash bash skills/plausible-analytics/scripts/track.sh \ --domain "$PLAUSIBLE_SITE_DOMAIN" \ --url "https://example.com/blog/post-1" \ --referrer "https://google.com" ``` Options: - `--domain` — Site domain (default: $PLAUSIBLE_SITE_DOMAIN) - `--url` — Page URL being viewed (required) - `--referrer` — Referring URL (optional) - `--base-url` — Plausible base URL (default: $PLAUSIBLE_BASE_URL) ## Track Custom Event ```bash bash skills/plausible-analytics/scripts/track.sh \ --domain "$PLAUSIBLE_SITE_DOMAIN" \ --event "Signup" \ --props "{\"plan\":\"pro\",\"source\":\"newsletter\"}" ``` Options: - `--domain` — Site domain - `--event` — Custom event name (e.g. "Signup", "Button Click") - `--props` — JSON object with event properties (optional) - `--base-url` — Plausible base URL ## Get Stats Summary ```bash bash skills/plausible-analytics/scripts/stats.sh \ --domain "$PLAUSIBLE_SITE_DOMAIN" \ --period "30d" \ --compare "previous_period" ``` Options: - `--domain` — Site domain - `--period` — Time period: `6mo`, `12mo`, `day`, `7d`, `30d`, `month` (default: 30d) - `--compare` — Compare to previous period: `previous_period` (optional) - `--base-url` — Plausible base URL (default: $PLAUSIBLE_BASE_URL) Returns: pageviews, unique visitors, bounce rate, visit duration, total pageviews ## Get Top Pages ```bash bash skills/plausible-analytics/scripts/top-pages.sh \ --domain "$PLAUSIBLE_SITE_DOMAIN" \ --period "30d" \ --limit 10 ``` Options: - `--domain` — Site domain - `--period` — Time period (default: 30d) - `--limit` — Number of pages to return (default: 10) - `--base-url` — Plausible base URL ## Get Realtime Visitors ```bash bash skills/plausible-analytics/scripts/realtime.sh \ --domain "$PLAUSIBLE_SITE_DOMAIN" ``` Options: - `--domain` — Site domain - `--base-url` — Plausible base URL Returns: current visitors on site, pageviews in last 30 min, top pages currently viewed ## Notes - The Events API (`/api/event`) is used without authentication for tracking - The Stats API (`/api/v1/stats`) requires `PLAUSIBLE_API_KEY` set in the request header - For self-hosted Plausible, set `PLAUSIBLE_BASE_URL` to your instance - All scripts output JSON or plain text depending on the endpoint

path: scripts/realtime.sh
content: #!/usr/bin/env bash
# realtime.sh — Get realtime visitor count from Plausible Analytics
# Usage: realtime.sh --domain "example.com" [--base-url "https://plausible.io"]

set -euo pipefail

DOMAIN="${PLAUSIBLE_SITE_DOMAIN:-}"
[REDACTED_SECRET]"
BASE_URL="${PLAUSIBLE_BASE_URL:-https://plausible.io}"

usage() {
  cat <<EOF
Usage: realtime.sh [options]
Options:
  --domain    Site domain (env: PLAUSIBLE_SITE_DOMAIN)
  --api-key   Plausible API key (env: PLAUSIBLE_API_KEY)
  --base-url  Plausible base URL (default: https://plausible.io)
EOF
  exit 1
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --domain) DOMAIN="${2:-}"; shift 2 ;;
    --api-key) [REDACTED_SECRET]"; shift 2 ;;
    --base-url) BASE_URL="${2:-}"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if [[ -z "$DOMAIN" ]]; then
  echo "Error: --domain or PLAUSIBLE_SITE_DOMAIN is required" >&2
  exit 1
fi

if [[ -z "$API_KEY" ]]; then
  echo "Error: --api-key or PLAUSIBLE_API_KEY is required" >&2
  exit 1
fi

PARAMS="site_id=${DOMAIN}"

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer ${API_KEY}" \
  "${BASE_URL}/api/v1/stats/realtime/visitors?${PARAMS}")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [[ "$HTTP_CODE" != "200" ]]; then
  echo "Error fetching realtime data (HTTP $HTTP_CODE): $BODY" >&2
  exit 1
fi

echo "$BODY" | jq .


path: scripts/stats.sh
content: #!/usr/bin/env bash
# stats.sh — Get Plausible stats summary (pageviews, visitors, bounce rate, duration)
# Usage: stats.sh --domain "example.com" [--period "30d"] [--compare "previous_period"] [--base-url "https://plausible.io"]

set -euo pipefail

DOMAIN="${PLAUSIBLE_SITE_DOMAIN:-}"
[REDACTED_SECRET]"
BASE_URL="${PLAUSIBLE_BASE_URL:-https://plausible.io}"
PERIOD="30d"
COMPARE=""

usage() {
  cat <<EOF
Usage: stats.sh [options]
Options:
  --domain    Site domain (env: PLAUSIBLE_SITE_DOMAIN)
  --api-key   Plausible API key (env: PLAUSIBLE_API_KEY)
  --period    Time period: 6mo, 12mo, day, 7d, 30d, month (default: 30d)
  --compare   Compare to previous period: previous_period (optional)
  --base-url  Plausible base URL (default: https://plausible.io)
EOF
  exit 1
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --domain) DOMAIN="${2:-}"; shift 2 ;;
    --api-key) [REDACTED_SECRET]"; shift 2 ;;
    --period) PERIOD="${2:-}"; shift 2 ;;
    --compare) COMPARE="${2:-}"; shift 2 ;;
    --base-url) BASE_URL="${2:-}"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if [[ -z "$DOMAIN" ]]; then
  echo "Error: --domain or PLAUSIBLE_SITE_DOMAIN is required" >&2
  exit 1
fi

if [[ -z "$API_KEY" ]]; then
  echo "Error: --api-key or PLAUSIBLE_API_KEY is required" >&2
  exit 1
fi

# Build query params
PARAMS="site_id=${DOMAIN}&period=${PERIOD}&display=badge"
if [[ -n "$COMPARE" ]]; then
  PARAMS="${PARAMS}&compare=${COMPARE}"
fi

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer ${API_KEY}" \
  "${BASE_URL}/api/v1/stats/aggregate?${PARAMS}")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [[ "$HTTP_CODE" != "200" ]]; then
  echo "Error fetching stats (HTTP $HTTP_CODE): $BODY" >&2
  exit 1
fi

# Pretty print the JSON
echo "$BODY" | jq .


path: scripts/top-pages.sh
content: #!/usr/bin/env bash
# top-pages.sh — Get top pages from Plausible Analytics
# Usage: top-pages.sh --domain "example.com" [--period "30d"] [--limit 10] [--base-url "https://plausible.io"]

set -euo pipefail

DOMAIN="${PLAUSIBLE_SITE_DOMAIN:-}"
[REDACTED_SECRET]"
BASE_URL="${PLAUSIBLE_BASE_URL:-https://plausible.io}"
PERIOD="30d"
LIMIT="10"

usage() {
  cat <<EOF
Usage: top-pages.sh [options]
Options:
  --domain    Site domain (env: PLAUSIBLE_SITE_DOMAIN)
  --api-key   Plausible API key (env: PLAUSIBLE_API_KEY)
  --period    Time period: 6mo, 12mo, day, 7d, 30d, month (default: 30d)
  --limit     Number of pages to return (default: 10)
  --base-url  Plausible base URL (default: https://plausible.io)
EOF
  exit 1
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --domain) DOMAIN="${2:-}"; shift 2 ;;
    --api-key) [REDACTED_SECRET]"; shift 2 ;;
    --period) PERIOD="${2:-}"; shift 2 ;;
    --limit) LIMIT="${2:-}"; shift 2 ;;
    --base-url) BASE_URL="${2:-}"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if [[ -z "$DOMAIN" ]]; then
  echo "Error: --domain or PLAUSIBLE_SITE_DOMAIN is required" >&2
  exit 1
fi

if [[ -z "$API_KEY" ]]; then
  echo "Error: --api-key or PLAUSIBLE_API_KEY is required" >&2
  exit 1
fi

PARAMS="site_id=${DOMAIN}&period=${PERIOD}&display=badge&limit=${LIMIT}"

RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer ${API_KEY}" \
  "${BASE_URL}/api/v1/stats/breakdown?${PARAMS}&property=event:page")

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [[ "$HTTP_CODE" != "200" ]]; then
  echo "Error fetching top pages (HTTP $HTTP_CODE): $BODY" >&2
  exit 1
fi

echo "$BODY" | jq .


path: scripts/track.sh
content: #!/usr/bin/env bash
# track.sh — Track pageviews and custom events to Plausible Analytics
# Usage: track.sh --url "https://example.com/page" [--referrer "https://ref.com"] [--domain "example.com"] [--base-url "https://plausible.io"]
#   or:  track.sh --event "Signup" [--props '{"plan":"pro"}'] [--domain "example.com"]

set -euo pipefail

DOMAIN="${PLAUSIBLE_SITE_DOMAIN:-}"
BASE_URL="${PLAUSIBLE_BASE_URL:-https://plausible.io}"
EVENT_NAME=""
URL=""
REFERRER=""
PROPS=""

usage() {
  cat <<EOF
Usage: track.sh [options]
Options:
  --domain    Site domain (env: PLAUSIBLE_SITE_DOMAIN)
  --url       Page URL for pageview events
  --referrer  Referring URL (optional)
  --event     Custom event name (e.g. Signup)
  --props     JSON object for event properties (optional)
  --base-url  Plausible base URL (default: https://plausible.io)
EOF
  exit 1
}

while [[ $# -gt 0 ]]; do
  case "$1" in
    --domain) DOMAIN="${2:-}"; shift 2 ;;
    --url) URL="${2:-}"; shift 2 ;;
    --referrer) REFERRER="${2:-}"; shift 2 ;;
    --event) EVENT_NAME="${2:-}"; shift 2 ;;
    --props) PROPS="${2:-}"; shift 2 ;;
    --base-url) BASE_URL="${2:-}"; shift 2 ;;
    -h|--help) usage ;;
    *) echo "Unknown option: $1"; usage ;;
  esac
done

if [[ -z "$DOMAIN" ]]; then
  echo "Error: --domain or PLAUSIBLE_SITE_DOMAIN is required" >&2
  exit 1
fi

# Pageview event
if [[ -n "$URL" ]]; then
  PAYLOAD=$(jq -n \
    --arg d "$DOMAIN" \
    --arg u "$URL" \
    --arg r "$REFERRER" \
    '{
      name: "pageview",
      url: $u,
      domain: $d,
      referrer: (if $r != "" then $r else null end)
    }')

  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD" \
    "${BASE_URL}/api/event")

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  if [[ "$HTTP_CODE" == "202" ]] || [[ "$HTTP_CODE" == "200" ]]; then
    echo "Pageview tracked: $URL"
  else
    echo "Error tracking pageview (HTTP $HTTP_CODE): $BODY" >&2
    exit 1
  fi

# Custom event
elif [[ -n "$EVENT_NAME" ]]; then
  if [[ -n "$PROPS" ]]; then
    PAYLOAD=$(jq -n \
      --arg d "$DOMAIN" \
      --arg e "$EVENT_NAME" \
      --json p "$PROPS" \
      '{
        name: $e,
        url: "https://" + $d + "/custom",
        domain: $d,
        props: $p
      }')
  else
    PAYLOAD=$(jq -n \
      --arg d "$DOMAIN" \
      --arg e "$EVENT_NAME" \
      '{
        name: $e,
        url: "https://" + $d + "/custom",
        domain: $d
      }')
  fi

  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD" \
    "${BASE_URL}/api/event")

  HTTP_CODE=$(echo "$RESPONSE" | tail -1)
  BODY=$(echo "$RESPONSE" | sed '$d')

  if [[ "$HTTP_CODE" == "202" ]] || [[ "$HTTP_CODE" == "200" ]]; then
    echo "Custom event tracked: $EVENT_NAME"
  else
    echo "Error tracking event (HTTP $HTTP_CODE): $BODY" >&2
    exit 1
  fi
else
  echo "Error: --url or --event is required" >&2
  usage
fi


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)