Plausible CLI

A Rust-native command-line interface that surfaces the Plausible Analytics APIs with a workflow tailored for humans and automation agents.

📝 Primary documentation lives in docs/llms-full.txt. It is authored in GitHub Flavored Markdown for LLMs and humans alike, and covers setup, command schemas, prompt snippets, and safety guidance.

Requirements

• Rust 1.90 or newer (rustup install stable recommended).
• A Plausible Analytics API key with access to the desired sites.

Installation

# Build and install from the current workspace
cargo install --path .

You can also run directly with cargo run -- <command> while developing.

First-Run Setup

Add your Plausible API key and friendly metadata with the accounts command:

plausible accounts add \
  --alias personal \
  --api-key PLAUSIBLE_API_KEY_HERE \
  --label "Personal Dashboard" \
  --email you@example.com

# Optionally set a different default account later
plausible accounts use --alias personal

Accounts are stored under ~/.config/plausible-cli/ with secrets held in a per-account key file when the OS keyring is unavailable. On macOS/Linux the CLI attempts to store credentials in the system keychain by default; you can opt out via PLAUSIBLE_CLI_DISABLE_KEYRING=1 for ephemeral or CI environments.

Usage Examples

List every site visible to the current account:

plausible sites list

Fetch aggregate visitors and pageviews for the last 7 days, returning JSON:

plausible stats aggregate \
  --site example.com \
  --metric visitors \
  --metric pageviews \
  --period 7d \
  --output json

Request a daily timeseries of visitors for the same site:

plausible stats timeseries \
  --site example.com \
  --metric visitors \
  --period 7d \
  --output json

Slice traffic by referrer with sorting and pagination:

plausible stats breakdown \
  --site example.com \
  --property visit:source \
  --metric visitors \
  --sort visitors:desc \
  --output json

Check realtime visitors currently online:

plausible stats realtime --site example.com --output json

Inspect the remaining API budget and next reset windows:

plausible status
plausible status --output json

Generate a sample custom event payload:

plausible events template
plausible events template --output json

Inspect the background queue (helpful when scripting bursts of API calls):

plausible queue inspect --output json
plausible queue drain   # block until all jobs finish

Multi-Account Workflow

• plausible accounts list – show all configured aliases (with default marker).
• plausible accounts export – print non-secret metadata (table) or --json for machine consumption.
• plausible accounts budget --alias <alias> [--daily <limit>|--clear] – set or clear a per-account daily request ceiling (defaults to hourly quota).
• Use --account <alias> on any command to override the default.

Machine-Friendly Mode

Every command accepts --output json so that automation agents can parse a stable structure. See docs/llms-full.txt for tips on driving the CLI from an LLM.

Project Docs

• docs/architeture.md – architecture overview and diagrams.
• docs/000-v1-plan.md – roadmap, milestones, and testing strategy.
• docs/llms-full.txt – LLM-oriented reference and prompt snippets.

Distribution

• GitHub Releases – Tags matching v* publish macOS and Linux archives in releases/. Download, extract, and copy the plausible binary onto your $PATH.
• Cargo install – cargo install plausible-cli --git https://github.com/vicentereig/plausible-cli.git --locked
• Homebrew (tap) – After the first tagged release:

  brew tap vicentereig/plausible-cli
  brew install plausible
  

  The formula used by the tap lives in homebrew/Formula/plausible.rb and is updated automatically during the release workflow. Until the dedicated tap repository is published, you can install the same formula locally:

  brew tap vicentereig/plausible-cli "$(pwd)/homebrew"
  brew install plausible
  

Testing

Run the suite (includes unit, async integration, and HTTP mocks):

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Contributing

Issues and PRs are welcome. Please run the commands in the Testing section before submitting changes. For new features, add coverage via unit/async tests and update the documentation when behavior changes.