# Umami Report > Per-site visitor & pageview reports from a private (self-hosted) Umami instance. - **Type:** Skill - **Install:** `agentstack add skill-gerodp-hermes-productivity-skills-umami-report` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [gerodp](https://agentstack.voostack.com/s/gerodp) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [gerodp](https://github.com/gerodp) - **Source:** https://github.com/gerodp/hermes-productivity-skills/tree/main/analytics/umami-report ## Install ```sh agentstack add skill-gerodp-hermes-productivity-skills-umami-report ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ` - 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: ```bash 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 ```bash SCRIPT=~/.hermes/skills/analytics/umami-report/scripts/umami_report.py ``` ### check — verify config + login ```bash python3 $SCRIPT check ``` Prints `OK — authenticated to ; 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) ```bash 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 `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 ```bash 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: ```bash python3 ~/.hermes/skills/analytics/umami-report/scripts/test_umami_report.py ``` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [gerodp](https://github.com/gerodp) - **Source:** [gerodp/hermes-productivity-skills](https://github.com/gerodp/hermes-productivity-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-gerodp-hermes-productivity-skills-umami-report - Seller: https://agentstack.voostack.com/s/gerodp - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.