@pluginauditor/cli

Audit a WordPress plugin for security, coding-standard, performance and compatibility issues from the terminal or CI. Powered by pluginauditor.com.

Zero dependencies. Runs on Node 18+.

Usage

# Scan your local plugin (before you ship it)
npx @pluginauditor/cli scan ./my-plugin.zip

# Scan a published WordPress.org plugin
npx @pluginauditor/cli scan --slug=woocommerce

Get a token

The CLI authenticates with a scan token tied to your account (separate from the full WordPress-plugin API key, so a leaked CI secret can only run scans, never manage sites or billing).

1. Sign in at app.pluginauditor.com.
2. Open Account → Access Tokens and create a token. Give it a name (e.g. "CI" or the repo name).
3. Copy the token when it's shown (it's shown once). You can revoke it any time from the same page.

Set it once in your shell, or pass --token on each run:

export PLUGIN_AUDITOR_TOKEN=your_token_here

In CI, store it as a secret (for example PLUGIN_AUDITOR_TOKEN in GitHub Actions) rather than committing it. Tokens are account-level, so the same token works across all your repos and machines; create a separate token per integration if you want to revoke them independently.

Options

| Flag | Description | |---|---| | --token <t> | API token (or PLUGIN_AUDITOR_TOKEN) | | --slug <s> | Scan a WordPress.org plugin by slug | | --version <v> | Specific version (with --slug). Omit to scan the plugin's latest release. | | --fail-on <sev> | Exit non-zero if any issue at/above this severity: critical | high | medium | low | none (default high) | | --category <list> | Only show findings in these categories (comma-separated): security, standards, performance, compatibility, privacy, accessibility | | --severity <list> | Only show findings at these severities (comma-separated): critical, high, medium, low, warning | | --json | Print the raw JSON result (never filtered) | | --sarif <file> | Also write a SARIF 2.1.0 report to <file> for GitHub code scanning (inline PR annotations) | | --no-annotate | Don't emit GitHub Actions inline annotations (auto-on inside Actions) | | --timeout <s> | Max seconds to wait (default 300) | | --api-url <url> | API base URL (or PLUGIN_AUDITOR_API_URL) | | --color / --no-color | Force or disable colored output |

Exit codes: 0 clean (under threshold), 1 threshold breached, 2 error.

Filtering the report

--category and --severity narrow the findings shown. They also scope the --fail-on exit gate, so a filtered run gates on exactly what it reports, which makes it easy to gate CI on one concern:

# Fail the build only on high or critical security issues
npx @pluginauditor/cli scan ./plugin.zip --category=security --severity=high,critical --fail-on=high

The overview always shows the active filter and an N of M issues shown count, so a filtered report is never mistaken for a clean one. The raw --json output is never filtered.

In CI (GitHub Actions)

Fail the build when a plugin has high-severity issues:

name: Plugin Audit
on: [pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: zip -qr plugin.zip . -x '.git/*'
      - run: npx @pluginauditor/cli scan ./plugin.zip --fail-on=high
        env:
          PLUGIN_AUDITOR_TOKEN: ${{ secrets.PLUGIN_AUDITOR_TOKEN }}

Example output

Findings are grouped by file (phpcs / WPCS style) with a per-file summary, then one row per finding in aligned columns: Category | Check name | Severity | Line | Issue. Warnings are included; plugin-level findings (no file/line) get their own block. The --fail-on threshold controls the exit code for CI; it is not printed as a verdict.

A SCANNING DETAILS overview is printed at the top and the bottom: plugin name/version, the scan date (in the machine's local timezone, with the zone shown), engine, total issues, per-category score /100 (checks passed/total) (matching the web report's category cards), issue totals by severity, and the report link.

The findings are wrapped in FINDINGS START / FINDINGS END banners (the SCANNING DETAILS overview sits outside them, at the top and bottom) so the report is easy to scan in CI logs. Each finding's Report link opens the full hosted report on pluginauditor.com, with the "How to fix" guidance for every issue.

Output is colored when it is written to a terminal (scores green/amber/red, severities red/amber, banners cyan) and plain when piped or redirected, so CI logs stay clean. Colors follow the NO_COLOR and FORCE_COLOR conventions, and --color / --no-color override the auto-detection.

SCANNING DETAILS
──────────────────────────────────────────────────────────────────────────────
Plugin Name               Hello Dolly
Plugin Version            1.7.2
Scan Date                 Sep 6, 2026, 3:36 PM GMT+5:30
Scanning Engine Version   2.0.0
Total Issues              19 issues found
Scores                    Security 51/100 (19/37)
                          Code Quality 85/100 (52/61)
                          Performance 42/100 (5/12)
                          Compatibility 33/100 (2/6)
                          Privacy 67/100 (2/3)
                          Accessibility 33/100 (2/6)
Severity                  3 high · 2 medium · 14 warnings
Report                    https://app.pluginauditor.com/scan/…
──────────────────────────────────────────────────────────────────────────────

════════════════════════════  FINDINGS START  ════════════════════════════

FILE: hello.php
──────────────────────────────────────────────────────────────────────────────
FOUND 3 high, 2 medium, 3 warnings AFFECTING 4 LINES
──────────────────────────────────────────────────────────────────────────────
  Standards | WordPress Alternative Functions  | WARNING  | 49 | mt_rand() is discouraged. Use wp_rand().
  Security  | Output Escaping (XSS Prevention) | HIGH     | 62 | All output should be escaped, found '__'.
  Security  | Output Escaping (XSS Prevention) | HIGH     | 63 | … found '$lang'.
──────────────────────────────────────────────────────────────────────────────

════════════════════════════  FINDINGS END  ════════════════════════════

SCANNING DETAILS
──────────────────────────────────────────────────────────────────────────────
Plugin Name               Hello Dolly
Plugin Version            1.7.2
Scan Date                 Sep 6, 2026, 3:36 PM GMT+5:30
Scanning Engine Version   2.0.0
Total Issues              19 issues found
Scores                    Security 51/100 (19/37)  ·  …
Severity                  3 high · 2 medium · 14 warnings
Report                    https://app.pluginauditor.com/scan/…
──────────────────────────────────────────────────────────────────────────────

License

MIT