Supalytics - Web Analytics

Query web analytics data using the Supalytics CLI. Use when the user wants to check pageviews, visitors, top pages, traffic sources, referrers, countries, revenue metrics, conversions, funnels, events, or realtime visitors.

Security Scan

The skill's documentation and commands match its analytics purpose, but there are a few inconsistencies and mild installation risks (missing declared dependencies, use of curl|bash installer, and implicit tools like jq) that you should verify before installing or running it.

Purpose & Capability

The name/description (querying web analytics via the Supalytics CLI) line up with the runtime instructions and required binary (supalytics). The commands and examples are coherent with an analytics CLI.

Instruction Scope

SKILL.md instructs installing Bun and the @supalytics/cli, using supalytics commands, and handling OAuth device flow by capturing and presenting a verification URL. It does not instruct reading unrelated files or environment variables. Minor scope issues: the doc uses jq in examples but jq is not declared as a required binary; the instructions also run a global installer (bun add -g) which affects the host environment.

Install Mechanism

There is no formal install spec; the README tells the user to run curl -fsSL https://bun.sh/install | bash (a remote install script) and then bun add -g @supalytics/cli. While bun.sh is an official site, curl|bash patterns are higher risk because they execute remote code; global installs modify the host environment. The skill does not declare Bun as a required binary despite requiring it in the install steps.

Credentials

The skill requests no environment variables or secrets and relies on OAuth device flow for auth, which is proportionate. Note: OAuth requires the agent to capture and present verification URLs and poll for completion — ensure the agent will not leak that data. Also, examples reference jq but jq is not declared as required.

Persistence & Privilege

always:false and normal autonomous invocation. The skill does not request persistent system-wide configuration or elevated privileges in its metadata. The only notable persistence is the implicit global installation via bun add -g, which writes to the host environment.

What to consider before installing

This skill appears to do what it claims (wrap the Supalytics CLI), but take these precautions before installing or running it: - Verify sources: bun.sh and @supalytics/cli come from public sources — confirm you trust bun.sh and the package registry before running curl | bash or global installs. - Prefer manual installs: instead of piping a remote script to bash, manually review the bun installer or install Bun via your OS package manager if available. Consider installing the CLI in a per-project environment rather than globally. - Confirm prerequisites: the SKILL.md requires Bun but the skill metadata only lists the supalytics binary; ensure Bun is installed and the supalytics binary is present. Examples use jq for JSON parsing — install jq if you need that behavior. - OAuth handling: the doc asks the agent to capture and display the OAuth verification URL and poll for completion. Only proceed if you trust the agent to not exfiltrate the URL or tokens; prefer doing the browser authorization yourself. - Scope and sandboxing: because the instruction set runs remote installers and global package installs, run it in a disposable/sandboxed environment (VM or container) if possible. If the publisher can update the skill to explicitly declare Bun (and jq if intended) in required binaries and avoid recommending curl|bash, that would reduce risk and make the package more coherent.

Supalytics CLI

Query web analytics data from Supalytics - simple, fast, GDPR-compliant analytics with revenue attribution.

Installation

Requires Bun runtime (not Node.js):

# Install Bun first
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"

# Install Supalytics CLI
bun add -g @supalytics/cli

Authentication

Important: OAuth in Agent Contexts

The supalytics login command uses OAuth device flow which requires user interaction in a browser. In agent contexts (OpenClaw, etc.), the process may be killed before OAuth completes.

Solution for OpenClaw: Use background: true mode:

await exec({
  command: 'supalytics login',
  background: true,
  yieldMs: 2000  // Wait 2s to capture the verification URL
});

The agent should:

1. Run login in background mode
2. Extract and present the verification URL to the user
3. Wait for user to complete browser authorization
4. Poll background session to check completion

Quick Setup

supalytics init    # Opens browser, creates site, shows tracking snippet

Manual Setup

supalytics login        # Opens browser for OAuth
supalytics sites add    # Create a new site

Commands

Quick Stats

supalytics stats              # Last 30 days (default)
supalytics stats today        # Today only
supalytics stats yesterday    # Yesterday
supalytics stats week         # This week
supalytics stats month        # This month
supalytics stats 7d           # Last 7 days
supalytics stats --all        # Include breakdowns (pages, referrers, countries, etc.)

Realtime Visitors

supalytics realtime           # Current visitors on site
supalytics realtime --watch   # Auto-refresh every 30s

Trend (Time Series)

supalytics trend              # Daily visitor trend with bar chart
supalytics trend --period 7d  # Last 7 days
supalytics trend --compact    # Sparkline only

Breakdowns

supalytics pages              # Top pages by visitors
supalytics referrers          # Top referrers
supalytics countries          # Traffic by country

Events

supalytics events                          # List all custom events
supalytics events signup                   # Properties for specific event
supalytics events signup --property plan   # Breakdown by property value

Custom Queries

The query command is the most flexible:

# Top pages with revenue
supalytics query -d page -m visitors,revenue

# Traffic by country and device
supalytics query -d country,device -m visitors

# Blog traffic from US only
supalytics query -d page -f "page:contains:/blog" -f "country:is:US"

# Hourly breakdown
supalytics query -d hour -m visitors -p 7d

# UTM campaign performance
supalytics query -d utm_source,utm_campaign -m visitors,revenue

# Sort by revenue descending
supalytics query -d page --sort revenue:desc

# Pages visited by users who signed up
supalytics query -d page -f "event:is:signup"

# Filter by event property
supalytics query -d country -f "event_property:is:plan:premium"

Available metrics: visitors, pageviews, bounce_rate, avg_session_duration, revenue, conversions, conversion_rate

Available dimensions: page, referrer, country, region, city, browser, os, device, date, hour, event, utm_source, utm_medium, utm_campaign, utm_term, utm_content

Site Management

supalytics sites                              # List all sites
supalytics sites add example.com              # Create site
supalytics sites update my-site -d example.com  # Update domain
supalytics default example.com                # Set default site
supalytics remove example.com                 # Remove site

Global Options

All analytics commands support:

Option	Description
-s, --site <domain>	Query specific site (otherwise uses default)
-p, --period <period>	Time period: 7d, 14d, 30d, 90d, 12mo, all
--start <date>	Start date (YYYY-MM-DD)
--end <date>	End date (YYYY-MM-DD)
-f, --filter <filter>	Filter: field:operator:value
--json	Output raw JSON (for programmatic use)
--no-revenue	Exclude revenue metrics
-t, --test	Query localhost/test data

Filter Syntax

Format: field:operator:value

Operators: is, is_not, contains, not_contains, starts_with

Examples:

-f "country:is:US"
-f "page:contains:/blog"
-f "device:is:mobile"
-f "referrer:is:twitter.com"
-f "utm_source:is:newsletter"
-f "event:is:signup"
-f "event_property:is:plan:premium"

Output Formats

Human-readable (default): Formatted tables with colors

JSON (--json): Raw JSON for parsing - use this when you need to process the data programmatically:

supalytics stats --json | jq '.data[0].metrics.visitors'
supalytics query -d page -m visitors --json

Examples by Use Case

"How's my site doing?"

supalytics stats

"What are my top traffic sources?"

supalytics referrers
# or with revenue
supalytics query -d referrer -m visitors,revenue

"Which pages generate the most revenue?"

supalytics query -d page -m revenue --sort revenue:desc

"How's my newsletter campaign performing?"

supalytics query -d utm_campaign -f "utm_source:is:newsletter" -m visitors,conversions,revenue

"Who's on my site right now?"

supalytics realtime

"Show me the visitor trend this week"

supalytics trend --period 7d

Troubleshooting

Issue	Solution
command not found: supalytics	Ensure Bun is installed and ~/.bun/bin is in PATH, or symlink to system path (see below)
No site specified	Run supalytics default <domain> to set default site
Unauthorized	Run supalytics login to re-authenticate
No data returned	Check site has tracking installed, try -t for test mode

OpenClaw / Daemon Usage

Bun installs to ~/.bun/bin which isn't in PATH for daemon processes like OpenClaw. After installation, symlink to system path:

sudo ln -sf ~/.bun/bin/bun /usr/local/bin/bun
sudo ln -sf ~/.bun/bin/supalytics /usr/local/bin/supalytics