Pluginator User Guide

Last Updated: February 21, 2026

Complete guide to using Pluginator for Minecraft server plugin management.

Getting Started
Interactive Mode
Command Line Usage
Plugin Configuration
Server Configuration
Update Checking
Sync Workflow
Migrate Workflow
Backup System
Health Dashboard
Performance Analytics
Recommendations
Templates
Organization
Theming
Troubleshooting

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:

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

Auto-Source Assignment (v2.2.0): After scanning, Pluginator automatically matches your plugins to the curated registry and assigns optimal update sources. Manually configured sources are never overwritten.

Path Validation (v2.1.2): 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 (v2.1.2): 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)
├── 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

Navigation

The UI has 9 tabs:

Home - Dashboard with quick actions and status
Servers - Side-by-side comparison of production vs test
Plugins - Full plugin list with search and filtering
Updates - Available updates with changelog view
Logs - Application logs with filtering
Stats - Plugin statistics and metrics (Plus tier)
Health - Plugin health scores and issues (Pro tier)
Recommendations - Smart plugin recommendations (Pro tier)
Performance - Server performance analytics (Pro tier)

Press 1-9 to jump directly to any tab. Tabs requiring a higher tier show a lock icon.

Logs Tab (v1.3.0)

The Logs tab provides real-time access to application logs with the following features:

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)

Reading Logs:

Each log entry shows:

Timestamp
Level indicator
Message
Context (structured data about the operation)
Duration (if operation took significant time)

Keyboard Shortcuts

Pluginator uses a state-aware input system (v1.4.0) 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-9`	Jump to tab (Home/Servers/Plugins/Updates/Logs/Sync/Health/Recs/Perf)
`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
`?`	Show help overlay
`Ctrl+C`	Quit (press twice)	2s timeout
`Ctrl+D`	Jump to Logs tab	Quick access

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
`/update`	Check for Pluginator updates
`/help`	Display keyboard shortcuts
`/quit`	Exit Pluginator

See COMMANDS.md for the full list of 74+ commands.

Command Palette Navigation:

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

Subscription Tiers

Pluginator uses a tiered subscription system. Some features require a higher tier:

Feature	Free	Plus	Pro	Max
Scan, Sync, Backup, Updates	Yes	Yes	Yes	Yes
Stats Dashboard	-	Yes	Yes	Yes
Health Dashboard	-	-	Yes	Yes
Recommendations	-	-	Yes	Yes
Performance Analytics	-	-	Yes	Yes
Theme Marketplace	-	-	-	Yes

Locked tabs show a lock icon in the header. Attempting to access a locked tab shows an upgrade notification. Commands requiring a higher tier are hidden from the command palette.

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)
--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 Backup

pluginator backup

Options:

-o, --output <path> - Custom backup location
-t, --type <type> - Backup type (prod, test, both)

View Logs

View and search application logs (v1.3.0):

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

# View today's logs
pluginator logs --since 2025-01-16

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

# Get machine-readable JSON output
pluginator logs --json --since 2025-01-16

Other Commands

# Run setup wizard
pluginator setup

# Show help
pluginator --help

# Show version
pluginator --version

# Use specific theme
pluginator --theme ocean

Plugin Configuration

Plugins are configured in plugins.json:

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

Spigot Plugins

Find the resource ID in the Spigot URL: https://www.spigotmc.org/resources/essentialsx.9089/ ^^^^

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

Modrinth Plugins

Use the project slug from the URL: https://modrinth.com/plugin/luckperms ^^^^^^^^^

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

GitHub Plugins

Use owner/repo format:

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

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
}

Server Configuration

Configuration is stored at ~/.pluginator/config.json. Edit it interactively with the /config-edit command, 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

Environment Variables

# Enable debug logging
PLUGINATOR_DEBUG=1 pluginator

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

Update Checking

How It Works

Pluginator reads your plugins.json
For each enabled plugin, queries the appropriate API
Compares installed version with latest available
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
CurseForge	Varies	Requires API key

Sync Workflow

Sync copies plugins from production to test server.

Process

Scans production plugins directory
Compares with test server plugins
Identifies new or updated plugins
Copies files to test server
Handles disableOnTest plugins by adding .disabled suffix

Use Cases

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

Migrate Workflow

Migrate moves tested plugins from test to production.

Process

Creates automatic backup of production
Scans test server plugins
Validates changes
Copies files to production
Cleans up old versions if needed

Safety Features

Automatic backup before migration
Dry-run mode for preview
Confirmation prompts
Rollback instructions in logs

Backup System

Creating Backups

Backups are tar.gz archives containing:

All plugin JAR files
plugins.json configuration
Timestamp in filename

Automatic Cleanup

Old backups are automatically removed based on MAX_BACKUPS setting.

Backup Naming

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

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

Restoring from Backup

# Extract backup
tar -xzf backup-prod-2025-01-15T10-30-00.tar.gz -C /path/to/restore

# Copy to server
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 Gallery

Requires Max tier

Browse and install community themes from the theme gallery:

# Open the theme gallery in interactive mode
# Use the command palette: /themes

The gallery loads themes from the NinSys API. If offline, a bundled gallery of curated themes is available as a fallback.

See THEME_SYSTEM.md for full theme documentation.

Health Dashboard

Added in v2.0

The Health Dashboard (Tab 7) provides 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
/conflicts - View plugin conflicts

See Health System for full details.

Performance Analytics

Added in v2.0

The Performance Dashboard (Tab 9) monitors server performance:

Metrics

TPS (Ticks Per Second)
Memory usage
Player count
Plugin load times

Features

Real-time metrics display
Historical charts
Configurable alerts
Baseline detection

Panel Integrations

Connect to server management panels:

AMP
Pterodactyl
Crafty Controller
MCSManager

See Analytics for full details.

Recommendations

Added in v2.0

The Recommendations tab (Tab 8) suggests plugins based on:

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

Commands

/recs - Open recommendations

Templates

Added in v2.0

Apply pre-configured plugin bundles:

/templates

Built-in Templates

Survival Server - EssentialsX, LuckPerms, Vault, WorldGuard
Creative Server - WorldEdit, FAWE, PlotSquared
Minigames - Citizens, HolographicDisplays, PlaceholderAPI
Network Hub - DeluxeHub, ServerSelectorX, TAB

See Templates for full details.

Organization

Added in v2.0

Organize plugins with:

Tags - Custom labels for filtering (/tags)
Groups - Collections for bulk actions (/groups)
Profiles - Saved configurations (/profiles)
Favorites - Quick access to frequent plugins (/favorites)

See Organization for full details.

Troubleshooting

Common Issues

"No plugins found"

Check your plugins.json file exists
Verify the JSON syntax is valid
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

"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

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 (v1.4.0) - Accepted/rejected inputs with reasons
State transitions (v1.4.0) - UI state changes with triggers
Throttled operations (v1.4.0) - Rate-limited action attempts

Input Validation Logging:

When debug mode is enabled, all keyboard inputs are validated against the current UI state and logged:

{
  "level": "debug",
  "message": "Input rejected: 's' in progress state",
  "timestamp": "2025-01-16T10:30:45.123Z",
  "context": {
    "key": "s",
    "state": "progress",
    "valid": false,
    "reason": "operation in progress"
  }
}

State Transition Logging:

UI state changes are tracked with triggers:

{
  "level": "info",
  "message": "UI state transition: idle → command-palette",
  "timestamp": "2025-01-16T10:30:45.456Z",
  "context": {
    "from": "idle",
    "to": "command-palette",
    "trigger": "/ or :"
  }
}

This helps diagnose:

Why certain keys aren't working (wrong state)
Unexpected state transitions
Race conditions with async operations

Getting Help

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

Log Files

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

~/.pluginator/logs/
├── pluginator-2026-02-21.log
├── pluginator-2026-02-20.log
└── ...

Log files are created daily and automatically cleaned up.

FilesExpand file tree

USER_GUIDE.md

Latest commit

History

USER_GUIDE.md

File metadata and controls

Pluginator User Guide

Table of Contents

Getting Started

Prerequisites

Initial Setup

User Data Directory

Interactive Mode

Navigation

Logs Tab (v1.3.0)

Keyboard Shortcuts

Global Keys (Available in Idle State)

State-Specific Keys

Command Palette

Subscription Tiers

Command Line Usage

CLI-Only Mode

Check for Updates

Sync Plugins

Migrate Plugins

Create Backup

View Logs

Other Commands

Plugin Configuration

Spigot Plugins

Modrinth Plugins

GitHub Plugins

Optional Fields

Server Configuration

Environment Variables

Update Checking

How It Works

Version Comparison

Rate Limiting

Sync Workflow

Process

Use Cases

Migrate Workflow

Process

Safety Features

Backup System

Creating Backups

Automatic Cleanup

Backup Naming

Restoring from Backup

Theming

Selecting a Theme

Theme Gallery

Health Dashboard

Health Scores

Health Grades

Commands

Performance Analytics

Metrics

Features

Panel Integrations

Recommendations

Commands

Templates

Built-in Templates

Organization

Troubleshooting

Common Issues

Debug Mode

Getting Help

Log Files