Skip to content

USER_GUIDE.md

Latest commit

 

History

History
1086 lines (773 loc) · 33.5 KB

USER_GUIDE.md

File metadata and controls

1086 lines (773 loc) · 33.5 KB
Raw

Pluginator User Guide

Last Updated: June 12, 2026

Complete guide to using Pluginator for Minecraft server plugin management.

Table of Contents

Getting Started

Prerequisites

Install Pluginator using your preferred method. See INSTALLATION.md for all options.

# macOS
brew tap NindroidA/pluginator && brew install pluginator

# Windows
scoop bucket add pluginator https://github.com/NindroidA/scoop-pluginator && scoop install pluginator

# npm (any platform)
npm install -g @nindroidsystems/pluginator

Initial Setup

Run the setup wizard:

pluginator setup

This will guide you through:

  1. Setting your production server path (with path validation)
  2. Setting your test server path (with path validation)
  3. Selecting Minecraft version and server type
  4. Configuring features, panel connections, and notifications
  5. Scanning for existing plugins
  6. Auto-assigning update sources from the curated registry

Auto-Source Assignment: After scanning, Pluginator automatically matches your plugins to the curated registry (104 plugins) and assigns optimal update sources. Manually configured sources are never overwritten. Re-run via /auto-source at any time.

Path Validation: When you enter a server path, Pluginator verifies the directory exists and contains plugin JAR files. If validation fails, you can:

  • Retry — Re-enter the path (your previous input is pre-filled)
  • Continue Anyway — Proceed without plugins (useful for new server setups)

Cached Paths: Re-running the setup wizard pre-fills paths from your current config, so you don't have to retype them.

User Data Directory

Pluginator stores its data at ~/.pluginator/:

~/.pluginator/
├── config.json             # User configuration
├── custom-registry.json    # User plugin registry entries
├── custom-sources.json     # User source overrides
├── session.json            # Auth session (encrypted)
├── notifications.json      # Notification history (v2.9.1)
├── .salt                   # Encryption salt
├── servers/                # Per-server plugin data
│   └── <server-id>/
│       └── plugins.json
├── backups/                # Backup archives
├── cache/                  # Cache files
└── logs/                   # Application logs

Interactive Mode

Launch the interactive terminal UI:

pluginator

The UI was overhauled in the v2.7.x series with a unified design system:

  • Bordered Panel components wrap every major section with embedded titles and footers
  • EnhancedTable drives the Plugins / Updates / Servers / Health views with auto-sized columns and responsive column hiding
  • KeyHintsBar at the bottom of every view shows context-relevant shortcuts
  • EmptyState components replace blank views with centered icon/title/description/action layouts
  • Scrollbar appears on long lists with a track (│) and thumb (┃)
  • Breadcrumb shows your navigation trail (Tab > Name > Detail)

Tabs

The UI has 8 tabs:

# Tab Description Tier
1 Home Dashboard with Server Status, Updates, and Quick Actions cards Free
2 Servers Side-by-side comparison of production vs test plugins Plus
3 Plugins Full plugin list with search, filtering, and detail panel Free
4 Updates Available updates with progress + changelog view Free
5 Logs Application logs with filtering and auto-scroll Plus
6 Stats Plugin statistics, source breakdowns, version distribution Plus
7 Health Plugin health scores, security advisories, compatibility Pro
8 Recs Smart plugin recommendations Pro

Press 1–8 to jump to a tab. Tabs requiring a higher tier display a lock icon and strikethrough; pressing the shortcut shows an upgrade notification.

The visible tabs in the header can be customized via /tabs (Tab Visibility).

Home Dashboard

The Home view is now a true dashboard (v2.7.12):

  • Server Status card — prod/test paths, plugin counts, last scan time
  • Updates card — total available, last check time, error count
  • Quick Actions grid — Scan / Sync / Check Updates / Backup buttons
  • On terminals ≥120 columns wide, Server Status and Updates are shown side-by-side
  • A startup tips panel rotates 20 tier-aware tips below the cards (v2.9.0)

Logs Tab

The Logs tab provides real-time access to application logs (Plus tier).

Keyboard Shortcuts in Logs:

  • f — Filter by log level (All / Info / Warn / Error / Debug)
  • a — Toggle auto-scroll (automatically scroll to newest logs)
  • r — Refresh logs
  • Ctrl+D — Quick access from any tab

Features:

  • Color-coded log levels for easy identification
  • Duration indicators for slow operations (>100ms shown in yellow, >1000ms in red)
  • Structured context display for detailed operation information
  • Daily log files with automatic cleanup

Log Levels:

  • Info (blue) — Normal operation events
  • Warn (yellow) — Non-critical issues
  • Error (red) — Failures and exceptions
  • Debug (gray) — Detailed diagnostic information (requires PLUGINATOR_DEBUG=1)

Keyboard Shortcuts

Pluginator uses a state-aware input system that validates keys against the current UI state.

Global Keys (Available in Idle State)

Key Action Notes
Tab Next tab
Shift+Tab Previous tab
1–8 Jump to tab Locked tabs show upgrade prompt
j / ↓ Move down
k / ↑ Move up
g Jump to top
G Jump to bottom
Space Toggle selection
Enter Confirm action
Esc Cancel/close dialog Context-dependent
/ or : Open command palette
Ctrl+P Open quick actions palette
? Show help overlay
Ctrl+C Quit (press twice) 2s timeout
Ctrl+D Jump to Logs tab Plus tier
Ctrl+O Jump back (vim-style) Plus tier
Ctrl+I Jump forward (vim-style) Plus tier

State-Specific Keys

Keys may be disabled in certain UI states:

Progress State (operation running):

  • Only Esc (if cancellable) and Ctrl+C work
  • All other keys are ignored to prevent accidental actions

Command Palette (when / or : is pressed):

  • ↑ / ↓ — Navigate commands
  • Enter — Execute command
  • Esc / Ctrl+C — Close palette
  • Any printable character — Search

Dialogs (confirmations, selections):

  • Navigation and confirmation keys only
  • Other actions disabled until dialog is closed

Help/Config Overlays:

  • Any key closes the overlay
  • Returns to previous state

Command Palette

Press / or : to open the command palette. Type to search commands.

Common commands:

Command Description
/scan Scan plugin directories on both servers
/sync Sync plugins from production to test
/updates Check all plugins for available updates
/backup Create a backup of plugin directories
/setup Run the setup wizard
/config-edit Edit configuration interactively
/themes Browse and install community themes (Max tier)
/login Login to your Pluginator account
/account View account, tier, and today's usage
/notifications View notification history
/plugin-edit Edit a plugin's update source and settings
/schedule Configure automatic update checking (Pro tier)
/history View operation history
/reset Clear cache, logs, and session (preserves config)
/selfupdate Check for Pluginator updates and auto-install
/help Display keyboard shortcuts
/exit Exit Pluginator

See COMMANDS.md for the full list of ~75 commands.

Command Palette Navigation:

  • ↑ / ↓ — Navigate through commands
  • Enter — Execute selected command
  • Esc — Close palette
  • Commands requiring a higher tier are hidden automatically

Quick Actions Palette

Press Ctrl+P to open the quick actions palette — a streamlined fuzzy finder over your most-used actions, plugins, and bookmarks. Use it when you know roughly what you want but don't remember the exact command name.

Subscription Tiers

Pluginator uses a tiered subscription system. The free tier is intentionally narrow — enough to try the workflow, but daily plugin management really starts at Plus.

Tier Price Update Checks/Day Downloads/Day Syncs/Day Migrations/Day
Free $0 1 5 1 0
Plus $9.99 (one-time) 10 50 5 3
Pro $2.99/mo or $24.99/yr 25 150 15 10
Max $4.99/mo or $44.99/yr Unlimited Unlimited Unlimited Unlimited

Feature Access

Feature Free Plus Pro Max
Scan, Sync, Backup, Updates Yes Yes Yes Yes
Home / Plugins / Updates tabs Yes Yes Yes Yes
Servers tab (prod vs test compare) — Yes Yes Yes
Logs tab — Yes Yes Yes
Stats Dashboard — Yes Yes Yes
Tags / Groups — Yes Yes Yes
Jump-list (Ctrl+O / Ctrl+I), chord shortcuts — Yes Yes Yes
Migrations (test → prod) — Yes Yes Yes
Health Dashboard — — Yes Yes
Recommendations — — Yes Yes
Scheduling + Test→Prod Promotion — — Yes Yes
Profiles / Macros / Vim mode — — Yes Yes
Export / Import — — Yes Yes
Theme Marketplace — — — Yes
Accessibility toggle — — — Yes

Plus tier holders receive a permanent discount on Pro/Max subscriptions. See TIER_SYSTEM.md for full details.

Command Line Usage

CLI-Only Mode

Use --no-ui to skip the interactive TUI:

pluginator --no-ui

This lists available CLI subcommands, useful for scripting and CI environments.

Check for Updates

pluginator check-updates

Options:

  • -t, --type <type> — Filter by source type (spigot, modrinth, github, hangar, etc.)
  • --all — Include disabled plugins

Sync Plugins

Copy plugins from production to test server:

pluginator sync

Options:

  • -f, --force — Overwrite existing files
  • --dry-run — Preview changes without copying

Migrate Plugins

Move plugins from test to production:

pluginator migrate

Options:

  • --no-backup — Skip automatic backup
  • --dry-run — Preview changes

Create or Restore Backup

# Create a backup
pluginator backup

# Restore from backup (use the -r flag)
pluginator backup -r ~/.pluginator/backups/backup-prod-2026-04-30T10-30-00.tar.gz

Options:

  • -o, --output <path> — Custom backup location
  • -t, --type <type> — Backup type (prod, test, both)
  • -r, --restore <file> — Restore the specified backup archive

View Logs

View and search application logs:

pluginator logs

Options:

  • --level <level> — Filter by level (info, warn, error, debug)
  • --grep <pattern> — Search for pattern in messages
  • --since <date> — Show logs since date (YYYY-MM-DD)
  • --follow — Real-time tail (like tail -f)
  • --json — Output raw JSONL format

Examples:

# View only errors
pluginator logs --level error

# Search for "sync" in logs
pluginator logs --grep sync

# Follow logs in real-time
pluginator logs --follow

# Get machine-readable JSON output
pluginator logs --json --since 2026-04-25

Other Commands

# Run setup wizard
pluginator setup

# Auto-update all plugins (scan + check + download)
pluginator auto-update

# Login / logout (or run /login in the UI)
pluginator login
pluginator logout

# Self-update Pluginator
pluginator self-update

# Show help / version
pluginator --help
pluginator --version

# Use specific theme
pluginator --theme ocean

Plugin Configuration

Plugins are configured in ~/.pluginator/servers/<server-id>/plugins.json. Use /plugin-edit (or /pedit) to edit interactively, or edit the file directly.

{
  "plugins": [
    {
      "name": "EssentialsX",
      "type": "spigot",
      "resourceId": "9089",
      "enabled": true
    }
  ]
}

Supported Sources

Pluginator supports 10 plugin sources:

Source type Identifier field Notes
Spigot spigot resourceId via Spiget API; premium resources become assisted updates
Modrinth modrinth projectSlug Generous rate limits
GitHub github repoSlug Owner/repo format
Hangar hangar projectSlug PaperMC's official catalog
GeyserMC geysermc projectName Bedrock support
Bukkit / CurseForge curseforge projectId API key required
Jenkins jenkins jobUrl Custom CI builds
Web Manifest web manifestUrl Self-hosted plugins (manifest commands)
Voxel (ex-Polymart) polymart resourceId Unauthenticated checks; POLYMART_TOKEN unlocks the sanctioned premium download
BuiltByBit builtbybit resourceId Metadata-only by design; BUILTBYBIT_TOKEN required for checks

Spigot Plugins

Find the resource ID in the Spigot URL:

https://www.spigotmc.org/resources/essentialsx.9089/ → 9089

{
  "name": "EssentialsX",
  "type": "spigot",
  "resourceId": "9089"
}

Modrinth Plugins

Use the project slug from the URL:

https://modrinth.com/plugin/luckperms → luckperms

{
  "name": "LuckPerms",
  "type": "modrinth",
  "projectSlug": "luckperms"
}

GitHub Plugins

Use owner/repo format:

{
  "name": "Vault",
  "type": "github",
  "repoSlug": "MilkBowl/Vault"
}

Hangar Plugins

Use the project slug from https://hangar.papermc.io/<author>/<slug>:

{
  "name": "Maintenance",
  "type": "hangar",
  "projectSlug": "Maintenance"
}

Optional Fields

{
  "name": "TestPlugin",
  "type": "spigot",
  "resourceId": "12345",
  "version": "1.0.0",            // Current installed version
  "enabled": true,                // Enable/disable (default: true)
  "disableOnTest": true,          // Disable when synced to test
  "mcVersion": "1.21.1",          // Target MC version
  "filenamePattern": ".*\\.jar",  // Regex for filename matching
  "notes": "Custom permissions"   // Free-form notes (v2.9.0)
}

Server Configuration

Configuration is stored at ~/.pluginator/config.json. Edit it interactively with /config-edit, or via the /setup wizard.

Key settings include:

  • Server paths — Production and test plugin directories
  • Minecraft version — Target version for compatibility checks
  • Backup settings — Retention count and backup directory
  • API keys — Optional GitHub token, CurseForge API key, marketplace buyer tokens
  • Post-action hooks — Shell commands to run after sync/download/backup/etc. (v2.9.0)

Automation Config Keys

These drive the update-automation pipeline:

Key Default Purpose
SERVER_PLATFORM bukkit Artifact selection for Hangar/Modrinth/GeyserMC: bukkit / velocity / bungeecord / folia
STRICT_COMPAT false Escalate "plugin targets a newer MC major than the server" from warn → block at install time
JAVA_MAJOR_VERSION (probe) Host JVM feature release (e.g. 21) for the Java class-version gate; unset ⇒ one java -version probe
DOWNLOADS_DIR ~/Downloads Directory pluginator complete scans for browser-downloaded files
POLYMART_TOKEN / BUILTBYBIT_TOKEN — Marketplace buyer tokens (optional)
IGNORED_PLUGINS [] Plugin names to skip from update tracking (array, or comma-separated string in the env config)

For unattended runs, export PLUGINATOR_TOKEN=<PAT> so the CLI is metered against your tier without an interactive login.

Environment Variables

# Enable debug logging
PLUGINATOR_DEBUG=1 pluginator

# Custom API endpoint
PLUGINATOR_API_URL=https://api.nindroidsystems.com

# Disable colors
NO_COLOR=1 pluginator

Update Checking

How It Works

  1. Pluginator reads your plugins.json
  2. For each enabled plugin, queries the appropriate API
  3. Compares installed version with latest available
  4. Reports which plugins have updates

Version Comparison

Pluginator handles various version formats:

  • Semantic: 1.0.0, 2.1.3
  • Prefixed: v1.0.0
  • Build numbers: 1.0.0-b123
  • Snapshots: 1.0.0-SNAPSHOT

Rate Limiting

Each source has rate limits:

Source Limit Notes
Spigot ~100/min Via Spiget API
Modrinth 300/min Generous limits
GitHub 60/hr 5000/hr with token
Hangar Generous PaperMC's official API
CurseForge Varies Requires API key

--ci Exit Codes

Both check-updates and auto-update accept --ci for machine monitoring. Without --ci, they exit 0 on success as usual. With --ci:

Code Meaning
0 Clean — nothing to do, nothing failed
1 Fatal error (also a cancelled auto-update run)
2 Partial failures — some plugins failed to check/download
10 Updates available (check) / applied or staged (auto-update)
20 ONLY manual/premium updates pending (no automatic ones)
30 An auth/tier gate refused an explicitly-requested gated feature 
pluginator check-updates --ci --json   # cron job: exit 10 == "go look"

Update Automation

auto-update is the one command that turns the update checker into update automation. It scans both servers, identifies each plugin (byte-exact sha256 hash lookups first, then registry / embedded watermark / URL hints), checks every plugin against its real source, and downloads available updates to the test server — every download passing the integrity gate before any swap.

# Check what would happen, change nothing
pluginator auto-update --dry-run

# Apply available updates to the test server
pluginator auto-update

# Headless / scripted
pluginator auto-update --json --ci

Safety rails on every run:

  • Identification first — the wrong-plugin class of bug is gone; updates only download for plugins matched to a known channel
  • Compat gates — Minecraft-version and Java class-version preflights block incompatible installs. Missing data never blocks; STRICT_COMPAT=true escalates "plugin targets a newer MC major than the server" from warn to block
  • Integrity gate — ZIP-magic + JAR scan + checksum are verified before the old JAR is touched; a bad download leaves the existing plugin intact
  • Running-server staging — if the test server is up, validated JARs are staged into Bukkit's plugins/update/ folder (reported as staged-for-restart) and apply on the next restart — never an in-place swap under a live JVM
  • Snapshot before swap — see Snapshots & Rollback
  • auto-update --export-manual writes a Markdown checklist of premium updates you need to download by hand

Use IGNORED_PLUGINS in your config to skip bespoke/private JARs with no public update channel (case-insensitive match on the scanned plugin name).

Source Identification & Review

When a scan can't auto-assign a source with high confidence, the suggestion goes to a review queue instead of being silently dropped:

pluginator assign --review            # list pending source suggestions (default)
pluginator assign --accept LuckPerms  # accept the best suggestion for one plugin
pluginator assign --accept-all        # accept all high-confidence suggestions

Premium / Assisted Updates

Premium and external-page plugins (paid SpigotMC, BuiltByBit, Voxel, or any plugin that only offers a browser download page) cannot be auto-downloaded under their terms of service. Pluginator handles them with an assisted flow rather than pretending they don't exist:

  1. Check — check-updates lists them under a "premium updates need manual download" block with the true version drift and a store deep-link:

    ! zAuctionHouse [premium]
    3.2.4.0 → 4.0.0.8
    https://www.spigotmc.org/resources/.../

  2. Download — open the deep-link in your browser and download the JAR (or the store's .zip) to your Downloads folder.

  3. Complete — match the downloaded file to the pending update and install it through the same integrity gate + snapshot path as an automatic download:

    pluginator complete                 # scan ~/Downloads for matching files
pluginator complete --dry-run       # show matches without installing
pluginator complete ./zAH-4.0.0.8.jar   # complete one specific file

    The scan directory defaults to DOWNLOADS_DIR (or ~/Downloads); override with --downloads-dir <path>. Only equal-or-newer versions install.

Self-Hosted Manifests

If you control a plugin's hosting, you can make it fully auto-updatable by publishing one static JSON manifest on any HTTPS host:

# Scaffold a schema-valid manifest
pluginator manifest new \
  --name MyPlugin \
  --plugin-version 1.4.0 \
  --download-url https://cdn.example.com/MyPlugin-1.4.0.jar \
  --sha256 <hash>            # optional, feeds the integrity gate

# Validate a manifest file or URL
pluginator manifest validate ./MyPlugin-manifest.json
pluginator manifest validate https://cdn.example.com/manifest.json

# Point a configured plugin at the manifest (sets type: web)
pluginator manifest add MyPlugin https://cdn.example.com/manifest.json

Note the flag is --plugin-version (not --version, which the CLI reserves for its own version output).

Snapshots & Rollback

Before every update swap, Pluginator archives the plugin's JAR and its data folder. Config migrations made jar-only rollbacks silently lossy, so both are captured. Snapshots are created automatically — there is no command to take one.

# List snapshots (all plugins, or one)
pluginator rollback
pluginator rollback CoreProtect --list

# Restore the newest snapshot for a plugin (test server by default)
pluginator rollback CoreProtect

# Restore a specific snapshot
pluginator rollback CoreProtect --snapshot <id>

# Restore the JAR only, skipping the data folder
pluginator rollback CoreProtect --no-data

# Roll back on the production server (must be explicit)
pluginator rollback CoreProtect --server prod

Restores are sha256-verified and rename-aside (the replaced JAR is kept, never rm -rf). The default target is the test server; --server prod is required to touch production.

Test → Prod Promotion

Updates install to the test server first and soak there (default 3 days) before they become promotable. Production is reachable only through this guarded path (or an explicit sync) — test installs never touch your production config.

# What's soaking / promotable / quarantined
pluginator promote --list

# Promote all promotable plugins to prod (drives the sync workflow + backup)
pluginator promote --apply

# Promote specific plugins
pluginator promote --apply LuckPerms Vault

# Plan only, mutate nothing
pluginator promote --apply --dry-run

# Block a bad update until a newer version supersedes it (--reason required)
pluginator promote --quarantine SomePlugin --reason "broke chat formatting"

# Full promotion store (current state + history)
pluginator promote --status

The soak window and exclude list come from your persisted schedule config (set via pluginator schedule --soak-days N). promote --apply refuses while the production server is running — restart orchestration is a later deployment milestone. Partial failures exit 2; a whole-run refusal exits 1.

Scheduling

Requires Pro tier. Schedule config persists across runs in ~/.pluginator/schedule-state.json.

# Enable scheduled checks at a daily interval (hourly | daily | weekly)
pluginator schedule --enable --interval daily

# Notify on unattended runs via a Discord/Slack-compatible webhook
pluginator schedule --webhook https://discord.com/api/webhooks/... --notify on

# Turn on scheduled test→prod promotion (runs inside auto-update) + soak window
pluginator schedule --promotion on --soak-days 3

# Print ready-to-paste cron / systemd / launchd / schtasks entries
pluginator schedule install-instructions

# Status / history
pluginator schedule --status
pluginator schedule --history

Pluginator does not run a background daemon. schedule install-instructions generates entries for your OS scheduler that invoke pluginator auto-update --json — a real command, with all the safety rails above. See DEPLOYMENT.md for the full run-on-host guide.

Sync Workflow

Sync copies plugins from production to test server.

Process

  1. Scans production plugins directory
  2. Compares with test server plugins
  3. Identifies new or updated plugins
  4. Copies files to test server
  5. Handles disableOnTest plugins by adding .jardis suffix

Use Cases

  • Testing updates before deploying to production
  • Setting up a new test server
  • Keeping test server in sync with production

Preview Sync

Use /preview (or pluginator sync --dry-run) to see exactly what a sync would do — no files are touched.

Config File Sync (v2.9.0)

The Servers tab can also discover and sync plugin YAML/JSON config files between servers (not just JARs). Use the /config-sync workflow to see which plugin configs differ between prod and test.

Migrate Workflow

Migrate moves tested plugins from test to production. Requires Plus tier.

Process

  1. Creates automatic backup of production
  2. Scans test server plugins
  3. Validates changes (compatibility checks against your MC version)
  4. Copies files to production
  5. Cleans up old versions if needed

Safety Features

  • Automatic backup before migration
  • Dry-run mode for preview
  • Confirmation prompts
  • Pre-update snapshots restorable with pluginator rollback <plugin> (or /rollback in the TUI) — see Snapshots & Rollback

Backup System

Creating Backups

Backups are tar.gz archives containing:

  • All plugin JAR files
  • plugins.json configuration
  • Timestamp in filename

Schedule automatic backups via /backups (Backup Schedule).

Automatic Cleanup

Old backups are automatically removed based on the MAX_BACKUPS setting in config.json.

Backup Naming

Format: backup-{type}-{timestamp}.tar.gz

Example: backup-prod-2026-04-30T10-30-00.tar.gz

Restoring from Backup

# Use the CLI (preferred)
pluginator backup -r ~/.pluginator/backups/backup-prod-2026-04-30T10-30-00.tar.gz

# Or extract manually
tar -xzf backup-prod-2026-04-30T10-30-00.tar.gz -C /path/to/restore
cp -r /path/to/restore/* /your/server/plugins/

Theming

Pluginator includes four built-in color themes:

Theme Description
default Purple/violet tones
ocean Blue/cyan tones
forest Green/emerald tones
sunset Orange/amber tones

Selecting a Theme

# Via command line
pluginator --theme ocean

# Via config file (~/.pluginator/config.json)
{
  "theme": "ocean"
}

Theme Marketplace

Requires Max tier

Browse and install community themes:

# Open the theme marketplace
/themes

The marketplace loads themes from the NinSys API. If offline, a bundled gallery of curated themes is available as a fallback. Themes can be installed by URL or browsed by category (dark / light / accessibility).

Health Dashboard

Requires Pro tier

The Health tab provides per-plugin health monitoring.

Health Scores

Each plugin receives a health score (0-100) based on:

  • Compatibility (40%) — Minecraft/server version support
  • Security (30%) — Known vulnerabilities, update recency
  • Update Status (30%) — Available updates, version age

Health Grades

Grade Score Meaning
A 90-100 Excellent
B 75-89 Good
C 60-74 Fair
D 40-59 Poor
F 0-39 Critical

Commands

  • /health — Open health dashboard
  • /deps — View the dependency graph

Recommendations

Requires Pro tier

The Recommendations tab suggests plugins based on:

  • Plugins commonly used together
  • Popular plugins you don't have
  • Similar alternatives to your plugins
  • Upgrade suggestions

Use /recs to open. Dismissed and saved recommendations persist between sessions.

Templates

Apply pre-configured plugin bundles via /templates.

Built-in Templates

  • Essential Starter — LuckPerms, Vault, EssentialsX
  • Economy Bundle — Vault + economy plugins
  • World Protection — WorldGuard, CoreProtect
  • Admin Tools — moderation, anti-cheat, logging

Organization

Organize plugins with:

  • Tags — Custom labels for filtering (/tags, Plus tier)
  • Groups — Collections for bulk actions (/groups, Plus tier)
  • Profiles — Saved configurations (/profiles, Pro tier)
  • Favorites — Quick access to frequent plugins (/favorites)

Plugin Notes & Config Sync

Plugin Notes (v2.9.0)

Add free-form notes to any plugin via /plugin-edit. Notes appear in the plugin detail panel and are stored in your local preferences (not on the plugin's JAR). Useful for tracking custom permissions, server-specific tweaks, or "do not auto-update" reminders.

Config File Sync (v2.9.0)

Beyond JAR sync, Pluginator can discover and sync plugin YAML/JSON config files between servers. Use it from the Servers tab to keep config drift in check between prod and test.

Notification History (v2.9.1)

All toast notifications are persisted to ~/.pluginator/notifications.json. Open /notifications to browse past notifications, see when each operation completed, and review error toasts you may have missed.

Post-Action Hooks

Added in v2.9.1

Configure shell commands to run after specific operations:

  • post-sync — After successful sync
  • post-download — After plugin download
  • post-backup — After backup creation
  • post-update-check — After update check completes
  • post-migrate — After migration to production

Configure via /config-edit under the hooks section. Hooks run with the operation's environment context as variables and are useful for restarting the server, sending Discord webhooks, or syncing with external tooling.

Security

As of v2.8.0, Pluginator hardens its HTTP layer:

  • SSRF blocklist — RFC 1918 / loopback / link-local addresses are refused for outbound requests, preventing a malicious source manifest from probing your internal network
  • Atomic file writes — All config writes use a temp-file + rename pattern so a crash mid-write can't corrupt your config
  • Token guidance — /config-edit flags tokens stored in plain config and recommends environment variables instead

Troubleshooting

Common Issues

"No plugins found"

  • Check your plugins.json file exists
  • Verify the JSON syntax is valid (/validate)
  • Ensure plugins have correct type and identifiers

"Failed to check updates"

  • Check your internet connection
  • Verify API keys if using GitHub or CurseForge
  • Check if the source API is accessible (try /auto-source to retry)

"Permission denied"

  • Ensure you have write access to server directories
  • Check file ownership
  • Run with appropriate permissions

"Version comparison failed"

  • Plugin may have non-standard version format
  • Set explicit version in plugin config

"Locked tab" notification

  • Servers / Logs / Stats require Plus, Health / Recs (and scheduling / promotion) require Pro, Theme Marketplace requires Max
  • See TIER_SYSTEM.md for full feature access

Debug Mode

Enable debug logging:

# Via environment variable
PLUGINATOR_DEBUG=1 pluginator

# Or in config file
PLUGINATOR_DEBUG=1

Debug logs include:

  • API requests and responses
  • Version comparison details
  • File operations
  • Input validation (accepted/rejected inputs with reasons)
  • State transitions (UI state changes with triggers)
  • Throttled operations (rate-limited action attempts)

Reset Options

Command Effect
/clearcache Clears the API/update cache only
/reset Clears cache, logs, and session — preserves config
/factoryreset Wipes everything (debug mode only)

Getting Help

  1. Check the Troubleshooting Guide
  2. Join the NindroidSystems Discord for quick community help
  3. Search existing issues
  4. Open a new issue with debug logs

Log Files

Logs are stored in ~/.pluginator/logs/:

~/.pluginator/logs/
├── pluginator-2026-04-30.log
├── pluginator-2026-04-29.log
└── ...

Log files are created daily and automatically cleaned up.