umami-report

name	umami-report
description	Per-site visitor & pageview reports from a private (self-hosted) Umami instance.
version	1.0.0
author	gerodp
license	MIT
platforms	["linux","macos","windows"]
required_environment_variables	[{"name":"UMAMI_URL","prompt":"Umami base URL (e.g. https://analytics.example.com)","required_for":"all functionality"},{"name":"UMAMI_USERNAME","prompt":"Umami username","required_for":"all functionality"},{"name":"UMAMI_PASSWORD","prompt":"Umami password","required_for":"all functionality"}]
metadata	{"hermes":{"tags":["umami","analytics","web-analytics","traffic","visitors","pageviews","reporting","self-hosted","stats"],"category":"analytics","requires_toolsets":["terminal"]}}

Umami Report

Report visitor and pageview numbers for every website on a private, self-hosted Umami analytics instance — in one command. Zero dependencies (Python stdlib only); all sites are queried concurrently so a full report returns in a couple of seconds. Each metric is shown with its delta versus the previous equal-length period (▲/▼).

Script path: ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py

When to Use

• User asks "how many visitors did my sites get?" / "traffic report" / "umami stats" / "pageviews this week/month" → report
• User wants one site only → report --site <name>
• User wants a specific window → report --days N or --since or --start/--end
• User wants machine-readable output to post-process → report --json

Prerequisites

Python 3.8+ (stdlib only — no installs). Three environment variables, injected automatically into the sandbox from ~/.hermes/.env: UMAMI_URL, UMAMI_USERNAME, UMAMI_PASSWORD.

Always run check first. If it reports missing variables, the user must set them themselves — guide them, do not collect secrets in chat:

hermes config           # edit config, or
$EDITOR ~/.hermes/.env  # add: UMAMI_URL=..., UMAMI_USERNAME=..., UMAMI_PASSWORD=...

~/.hermes/.env is mode 600. After editing, re-run check.

Secret Safety (MANDATORY)

• Never print, echo, cat, or interpolate $UMAMI_PASSWORD (or the other vars) into a command line, log, or chat message.
• Never ask the user to paste their password into the conversation — they set it in ~/.hermes/.env on their own machine.
• To confirm credentials work, use only the check command. The script is written to never print secrets or the auth token.

Commands

SCRIPT=~/.hermes/skills/analytics/umami-report/scripts/umami_report.py

check — verify config + login

python3 $SCRIPT check

Prints OK — authenticated to <url>; N website(s) visible. on success, or a clear, secret-free error. Exit code is non-zero on any failure.

report — per-site visit table (default)

python3 $SCRIPT report                       # all sites, last 7 days
python3 $SCRIPT report --days 30             # last 30 days
python3 $SCRIPT report --since today         # today so far
python3 $SCRIPT report --start 2026-06-01 --end 2026-06-07
python3 $SCRIPT report --site blog           # only sites matching "blog"
python3 $SCRIPT report --days 30 --json      # machine-readable

report is the default, so python3 $SCRIPT with no args == last 7 days.

Output columns: Site, Visitors, Visits, Pageviews, Bounce%, sorted by pageviews descending, with a TOTAL row. Visitors/Visits/Pageviews each show the ▲/▼ change versus the immediately preceding period of equal length. The --json output additionally carries site_id (the Umami website id, for telling multiple sites apart / verification), bounce_pct, avg_duration and avg_duration_prev (average visit duration in seconds) per site.

Present the table to the user as-is (it's already aligned). When they ask about a single number, read it from the relevant cell rather than re-querying.

Pitfalls

• --start/--end must be given together (YYYY-MM-DD); the end date is inclusive (counts the whole day). They override --days/--since.
• Dates/windows are computed in UTC for deterministic output; numbers may differ slightly from the Umami dashboard if it uses a local timezone.
• A wrong UMAMI_URL (or http vs https) shows up as a network/HTTP error from check — fix the env var, don't retry blindly.
• This skill targets self-hosted Umami (username/password login). Umami Cloud uses an x-umami-api-key header instead — not supported here.

Verification

python3 ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py check
# → "OK — authenticated to https://...; N website(s) visible."

python3 ~/.hermes/skills/analytics/umami-report/scripts/umami_report.py report
# → aligned table of all sites for the last 7 days, with a TOTAL row.

Offline unit tests (no network) live next to the script:

python3 ~/.hermes/skills/analytics/umami-report/scripts/test_umami_report.py