Plausible Automation Toolkit

Plausible Automation Toolkit is a macOS command-line tool and Codex skill for operating a self-hosted Plausible Community Edition instance. It can create a website property through the authenticated dashboard, install the tracking script in a project, produce traffic reports, and manage goals.

You supplies both values that identify their setup:

• the HTTPS origin of their own Plausible instance;
• the public domain of each website they operate.

No seller-owned domain, login, API key, plugin token, or analytics data is in this package.

Current release: 1.0.0.

Requirements

• macOS with the security and expect commands
• Python 3.10 or newer
• a self-hosted Plausible Community Edition account
• a website project with one shared file containing </head>
• Codex if you want natural-language skill triggering; the CLI works directly

The included implementation is intentionally macOS-first because all secrets are stored in login Keychain.

Install

Extract the download, open Terminal, and run:

cd 30-plausible-automation/code
./install.sh --plausible-url https://plausible.example.com

Replace the example URL with the HTTPS origin of your own Plausible instance. The installer copies the skill to ~/.codex/skills/setup-plausible and the CLI to ~/.local/bin/plausible-setup.

If ~/.local/bin is not on PATH, add this to ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then open a new Terminal window.

First run

Store the Plausible dashboard login in Keychain:

plausible-setup credentials

From a website project, preview and apply the integration:

plausible-setup setup --dry-run
plausible-setup setup

The CLI infers the tracked domain from Astro's site, package.json's homepage, or a dotted project-directory name. Override it whenever needed:

plausible-setup setup --domain shop.example.com --target src/layouts/Layout.astro

Health, reports, and goals

plausible-setup doctor --domain example.com
plausible-setup report --domain example.com --period 7d
plausible-setup report --domain example.com --period 30d --compare previous
plausible-setup breakdown --domain example.com --period 30d --by country
plausible-setup breakdown --domain example.com --by page --filter source=Google
plausible-setup report --domain example.com --format markdown
plausible-setup goals-list --domain example.com
plausible-setup goal-add --domain example.com --event Signup
plausible-setup goal-add --domain example.com --page '/thank-you*'

doctor checks the instance, tracker endpoint, project snippet, property, Stats API, and optional goal token without changing anything. Reports support text, JSON, CSV, and Markdown output. The first report creates a Stats API key through the authenticated dashboard and saves it in Keychain. Goal commands require one site-scoped plugin token; the CLI prints the exact dashboard URL and stores the resulting token through a secure Terminal prompt.

Codex use

After installation, ask Codex things like:

• “Install Plausible on this site.”
• “Show me Plausible traffic for the last 30 days.”
• “Add a Signup goal in Plausible.”

The skill tells Codex to inspect changes, keep secrets out of chat, preview tracker edits, and avoid Plausible's Sites API.

Verify the package

cd code
python3 -m unittest discover -s tests -v
python3 setup-plausible/scripts/plausible-setup --version

The eight tests use a local fake server. They do not contact Plausible, change a real site, or read you's Keychain.

Documentation

• CONFIGURATION.md — instances, domains, Keychain services, and overrides
• SECURITY.md — secret handling and mutation boundaries
• ARCHITECTURE.md — dashboard, Stats API, Plugins API, and project flows
• CUSTOMIZATION.md — extensions and portability seams
• DEPLOYMENT.md — installation, upgrades, and removal
• BUILDING.md — verification and release process
• AGENTS.md — invariants for AI coding agents

License

MIT. Keep the included license notice with substantial copies.

Overview

The toolkit has two entry points over one implementation:

flowchart TD
  developer["Developer / terminal"] --> cli["plausible-setup CLI"]
  request["Codex request"] --> skill["setup-plausible skill"] --> cli

  cli --> doctor["Doctor checks"]
  cli --> dashboard["Dashboard session"] --> property["Property + Stats key"]
  cli --> stats["Stats API v2"] --> reports["Traffic reports"]
  cli --> plugins["Plugins API"] --> goals["Goals"]
  cli --> tracker["Project tracker edit"]

  config["Config<br/>~/.config/plausible-setup/config.json"] -. settings .-> cli
  keychain["Secrets<br/>separate macOS Keychain items"] -. credentials .-> cli

  classDef entry fill:#332d23,stroke:#e8a830,stroke-width:2px,color:#f0e4cc
  classDef core fill:#c85520,stroke:#e8a830,stroke-width:2px,color:#fff8ea
  classDef service fill:#2d2a25,stroke:#a87628,color:#f0e4cc
  classDef output fill:#211f1c,stroke:#5b5143,color:#d2c4aa
  classDef storage fill:#25231f,stroke:#7c6b50,stroke-dasharray:5 4,color:#d2c4aa

  class developer,request,skill entry
  class cli core
  class doctor,dashboard,stats,plugins service
  class property,reports,goals,tracker output
  class config,keychain storage

Codex loads setup-plausible/SKILL.md when a request concerns installation, traffic reporting, or goals. The skill delegates deterministic work to the bundled CLI.

Configuration and identity

The Plausible origin is selected in this order:

1. --plausible-url for one invocation;
2. PLAUSIBLE_URL for one process environment;
3. the value saved by plausible-setup configure.

The tracked domain is selected independently from --domain, Astro's site, package.json's homepage, or the project directory name. This separation is what allows one CLI installation to operate many websites on one Plausible instance.

Dashboard flow

Property creation and Stats key generation use an authenticated cookie session. The CLI fetches the current HTML forms, preserves hidden inputs including CSRF tokens, submits the documented dashboard fields, follows redirects, and checks the resulting state. It does not use the Sites API.

Tracker flow

The CLI finds a shared layout or HTML file containing a standalone </head>, builds a script tag from the configured origin and resolved website domain, and produces a unified diff. It refuses ambiguous layouts and existing analytics snippets instead of guessing.

Reporting flow

The first report creates a Stats API key and hands the generated value directly to the Keychain helper over standard input. Reports query Stats API v2 for the summary, top pages, top sources, and goal conversions. Output can be human readable, JSON, CSV, or Markdown. Comparison reports calculate the immediately preceding calendar range locally and query both periods. Breakdowns map stable CLI aliases to Stats API dimensions and translate repeatable NAME=VALUE filters into structured API filters.

Diagnostic flow

doctor performs independent read-only checks and retains every result instead of stopping at the first problem. Missing optional keys are warnings; instance, tracker, property, project-snippet, or API failures make the command non-zero.

Goal flow

Each website has its own Plugins API token. The CLI authenticates with the tracked domain and token, then lists, creates, or deletes custom-event and pageview goals. Deletion requires both an exact numeric ID and --yes.