Before you start
An API key. On Umami Cloud that is any plan. Self-hosting, you need a version new enough to have Settings → API keys; an older instance cannot be connected at all, whatever key you paste.
Set it up
- Open Umami, or your own instance.
- Settings → API keys → Create API key. Name it
sprid. Umami shows it once. - Copy the key and leave it on your clipboard.
- Settings → Websites → the site → Details. Copy the Website ID. It is a uuid such as
8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44, not the domain.
Connect to Sprid
sprid connect umami --key-from-clipboard --site 8f2a1c90-4d1e-4b7a-9f33-2c0b5e7a1d44Self-hosting? Add --host https://analytics.example.com. Sprid appends the /api your instance serves under, so either form works. Add --use to make Umami the source Sprid reports website traffic from; Only one provider answers explains which provider answers when several are connected.
Typing the command yourself? Copy the key last, as Keys from your clipboard explains, with the fallback for a shell without a clipboard.
Check the connection
Run sprid status, then ask your agent: “Read this website’s visitors for the last 28 days through Sprid and say which provider answered.” A saved key confirms setup; only the live read confirms access.
If something goes wrong
- Unauthorized: the key cannot see this website, or your self-hosted Umami predates API keys. Check for the Settings → API keys screen; if there is none, upgrade first.
- Not found: you probably saved the domain instead of the website id, or left
/apioff a self-hosted host. Sprid adds/apifor you when you pass--host. - Rate limited: Umami Cloud is limiting requests. The next hourly read picks it up.
What Sprid can and cannot read here
Visitors, pageviews, visits, bounces and total time, plus every breakdown this product draws: country, region, city, referrer, channel, campaign, term, page, entry page, exit page, hostname, browser, operating system and device. Umami is the only alternative provider that reports an exit page.
Umami is cookieless, so window totals come from Umami directly and are never the daily numbers added up. The daily line counts sessions rather than distinct people, so it will not sum to the visitor total beside it.
Prefer your terminal? sprid docs umami reads this same guide.