Skip to content

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

umami-report

Verified

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

FileKindSize
SKILL.mdskill md4.9 KB
scripts/test_umami_report.pyexecutablescript13.6 KB
scripts/umami_report.pyexecutablescript16.7 KB
---
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:

```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 <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)

```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 `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

```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
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall