Plausible Automation Toolkit

Plausible Automation Toolkit operates an existing, self-hosted Plausible Community Edition instance. It includes the plausible-setup command and a Codex skill. You provide your own Plausible server and account.

Install and connect

You need macOS, Python 3.10 or later, and the system security and expect commands. After purchase, connect GitHub in Polar and accept the invitation to the customer repository.

Clone the repository and run its installer. Replace the example origin with your own Plausible instance:

./install.sh --plausible-url https://plausible.northstar.example

The installer puts the command in ~/.local/bin/plausible-setup and the skill in ~/.codex/skills/setup-plausible. If your shell cannot find the command, add ~/.local/bin to PATH and open a new Terminal window.

Store your dashboard login through the interactive credential prompt:

plausible-setup credentials

Credentials and generated API tokens are stored in macOS login Keychain. The instance configuration lives at ~/.config/plausible-setup/config.json.

Add tracking to a website

Open Terminal in the website’s source directory. Preview the integration before applying it:

plausible-setup setup --dry-run

The toolkit looks for a shared HTML or layout file containing </head>. It infers the tracked domain from Astro’s site, the package homepage, or a dotted directory name. The Plausible instance origin and the tracked domain are separate settings.

If the inferred values are wrong, provide them explicitly. This example targets a shared Astro layout for a fictional website:

plausible-setup setup --dry-run --domain shop.northstar.example --target src/layouts/Layout.astro

Read the proposed diff. Remove --dry-run to create the property when needed and insert the tracker. Commit and deploy that website change through your normal workflow.

The toolkit refuses an ambiguous layout or an existing analytics snippet. Choose the right --target and review the existing integration rather than adding duplicate trackers.

Check the integration

Run diagnostics for your tracked domain:

plausible-setup doctor --domain shop.northstar.example

doctor checks the instance, tracker endpoint, project snippet, site property, Stats API and optional goal token. It does not change the integration. A local snippet check and a reachable tracker do not by themselves prove the production page has been deployed; open your live website too.

Read a traffic report

Request the last 30 days and compare them with the previous period:

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

The first report creates a Stats API key through your authenticated dashboard session and saves it in Keychain. Reports support text, JSON, CSV and Markdown through --format.

Use a breakdown to inspect a dimension:

plausible-setup breakdown --domain shop.northstar.example --period 30d --by page --filter source=Google

Manage goals

List existing goals before adding one:

plausible-setup goals-list --domain shop.northstar.example

Add a custom-event goal or a page goal:

plausible-setup goal-add --domain shop.northstar.example --event Signup
plausible-setup goal-add --domain shop.northstar.example --page '/thank-you*'

Goal commands need a site-scoped plugin token. The CLI prints the appropriate dashboard URL and asks for the token through a secure Terminal prompt. Creating a custom-event goal does not add event-emitting code to your website; the website must send that event separately.

Agent use and troubleshooting

After installing the skill, ask Codex to show traffic, preview a tracker integration or add a named goal. Keep login details and API keys out of chat and source control.

For authentication errors, check the configured instance origin and run credentials again. Use --target when tracker setup cannot choose a layout. A report failure while the tracker works calls for checking Stats API access separately with doctor.

Back up the website’s source through Git and your Plausible server through its own backup process. Updating this toolkit does not back up or update the Plausible instance.