CLI + Skill · version 1.0

Plausible Automation Toolkit

A macOS CLI and Codex skill for self-hosted Plausible Community Edition. Configure your own analytics origin, create website properties, install trackers, report traffic, and manage goals without putting credentials in projects or AI chats.

Python 3Codex SkillmacOS KeychainPlausible CEStats API v2Plugins API

View on GitHub Download ZIP Read the docs

The full source, tests, and documentation live in the public repository. MIT licensed. Issues and pull requests are off: fork it and make it yours.

Why I built this

Adding Plausible to a site is small enough to do manually and repetitive enough to keep doing badly. The real workflow is more than one script tag: create the property, select the correct shared layout, avoid duplicate analytics, store the login safely, generate a reporting key, remember the Stats query shape, and configure goals later.

I built one local tool that handles that whole lifecycle. The deterministic CLI does the fragile work and the Codex skill supplies project-aware judgment: preview the edit, inspect the result, run the site checks, and turn a request like “install Plausible on this site” into a repeatable operation.

From project folder to useful analytics

Configure once. Operate every website with the same guarded workflow.

Set your own Plausible origin.
Create the property and install its tracker.
Query traffic through the Stats API.
Manage site-scoped conversion goals.

Features

Your Plausible domain

Configure the HTTPS origin of the self-hosted instance you own. No vendor or seller domain is baked in.

Per-project domain discovery

Infer each website from Astro site metadata, package homepage, or the project directory, with explicit overrides.

Property provisioning

Safe tracker insertion

Find the shared head, show a unified diff, preserve Astro inline behavior, and refuse duplicate analytics.

Traffic reports

Query visitors, visits, pageviews, bounce rate, visit duration, top pages, sources, and goals with previous-period changes.

Breakdowns and exports

Analyze countries, devices, campaigns, pages, goals, sources, and custom properties as text, JSON, CSV, or Markdown.

Read-only doctor

Check the instance, tracker endpoint, project snippet, property, Stats key, and optional Plugins API without changing them.

Goal management

List and create custom-event or pageview goals, and delete one exact goal only with explicit confirmation.

Separated Keychain secrets

Keep dashboard login, generated Stats key, and every site plugin token in distinct macOS Keychain items.

Natural-language operation

Install the included Codex skill and ask for Plausible installation, traffic summaries, or goal changes.

Tested local core

Run eight fake-server regression tests without contacting a real instance, website, or Keychain.

Use cases

Install analytics repeatedly

Use the same guarded workflow across an Astro portfolio, static landing pages, and client projects.

Ask for weekly traffic

Let Codex run a read-only report and explain the important pages, sources, and conversions in plain language.

Standardize launch checklists

Add property creation, tracker verification, and initial goals to a repeatable pre-launch workflow.

Operate several websites

Keep one configured Plausible instance while resolving and authenticating every tracked domain separately.

Learn reliable dashboard automation

Study CSRF-aware forms, cookie sessions, state verification, and fail-closed handling in plain Python.

Build a broader analytics operator

Add campaign, geography, device, comparison, export, health-check, or scheduled-report workflows.

Tech stack

Portable CLI core

Python 3

Uses the standard library for argument parsing, HTTP, cookie sessions, HTML forms, JSON, diffs, and project inspection.

Natural-language interface

Codex skill

Triggers on installation, traffic, and goal requests and guides the agent through previews, checks, and secret-safe handoffs.

Secret storage

macOS Keychain

Stores three credential classes under origin- and site-scoped service names without plaintext config files.

Community Edition setup

Plausible dashboard

Creates properties and Stats keys through authenticated, CSRF-aware form submissions with state verification.

Read-only analytics

Stats API v2

Supplies summary metrics, content, acquisition, and conversion data for text or JSON reports.

Site-scoped goals

Plugins API

Lists and changes custom-event and pageview goals through a token limited to one tracked website.

CLI

The included command is useful by itself and is also the deterministic execution layer behind the Codex skill. Every account-specific value is supplied by you or inferred from the current project.

plausible-setup configure --plausible-url https://plausible.example.com

Save the HTTPS origin of your own self-hosted Plausible instance.

plausible-setup credentials

Store the dashboard login through an interactive macOS Keychain prompt.

plausible-setup setup --dry-run

Resolve the website domain and shared layout, then preview property and tracker work.

plausible-setup setup --domain example.com

Create or find the property and install the matching tracker for one explicit website.

plausible-setup doctor --domain example.com

Run independent read-only checks across local setup and remote Plausible services.

plausible-setup report --domain example.com --period 30d --compare previous

Report important metrics and explain changes from the immediately preceding period.

plausible-setup breakdown --domain example.com --by country --format markdown

Break traffic down by a supported dimension and export a presentation-ready table.

plausible-setup goal-add --domain example.com --event Signup

Create or find a custom-event goal through the site-scoped Plugins API.

What’s included

Plausible Automation Toolkit version 1.0.0 with complete MIT-licensed source
Developer-configurable self-hosted Plausible origin with CLI, environment, and saved-config precedence
Per-project tracked-domain inference plus explicit domain and target overrides
Dashboard property provisioning with current hidden-field and CSRF token preservation
Dry-run tracker diffs, Astro-aware script insertion, and duplicate-integration refusal
Automatic Stats API key generation and rotation without exposing the generated secret
Read-only doctor checks for the Plausible origin, tracker, project snippet, property, Stats API, and Plugins API
Reports with summary, top pages, sources, goals, previous-period changes, and text, JSON, CSV, or Markdown output
Filtered breakdowns by geography, acquisition, technology, content, goals, and custom properties
Custom-event and pageview goal list, create, and confirmation-gated delete commands
Separate macOS Keychain identities for login, reporting, and each website plugin token
Installable Codex skill with tested trigger phrases and conservative operating instructions
One-command local installer plus eight regression tests using a fake Plausible server
A README with setup, architecture, security, configuration, customization, deployment, build, and decision guides, plus AGENTS.md for coding agents

Documentation

The documentation lives in the repository, in one README: setup and usage, why I built it, how it was built, architecture, configuration, deployment, customization, security, the technical decisions, and the changelog. AGENTS.md gives coding agents the project context and operating rules.

Read the README on GitHub →

Why use this

Stop rebuilding the same setup script and dashboard checklist for every website
Keep analytics credentials out of repositories, shell history, and AI conversations
Start with real property, report, and goal workflows instead of a script-tag snippet
Give Codex a focused, deterministic tool instead of broad browser access
Own a small standard-library codebase that is straightforward to inspect and extend
Reuse or resell a derivative under the permissive MIT license

Customize it

Use the working source as a foundation. Keep it small, change it for your own workflow, or turn it into a different product.

Add framework-specific domain and shared-layout discovery for the stack you use most.
Build previous-period comparisons and have your agent explain meaningful traffic changes.
Export CSV or Markdown reports for newsletters, client updates, or project journals.
Add country, device, campaign, entry-page, and exit-page sections through Stats API v2.
Port secret storage to Linux Secret Service or Windows Credential Manager behind the documented seam.
Turn it into a scheduled analytics operator with health checks, alerts, and weekly summaries.

MIT license

The repository includes an MIT LICENSE file. You can use, copy, change, publish, distribute, sublicense, or sell the code, including as part of a commercial product.

Keep the copyright and license notice with copies or substantial portions of the code. Third-party dependencies and assets keep their own licenses.

Keep learning

Ship Factory

See how a focused CLI and Codex skill turn a repeated operational job into an agent-ready workflow.

Explore Ship Factory →