Umami report

Skill gerodp/hermes-productivity-skills/analytics/umami-report

Productivity skills tap for the Hermes agent: weekly report, time-tracking, notes, email, calendar, git, and analytics.

Install

npx -y skills add gerodp/hermes-productivity-skills --skill umami-report

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Per-site visitor & pageview reports from a private (self-hosted) Umami instance.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.9 KB, as published. Nobody here has run it

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