Server Commands

Paper provides additional commands beyond vanilla Minecraft for server administration, debugging, and performance monitoring.

Paper Commands

The /paper command provides access to Paper-specific functionality. All subcommands require the bukkit.command.paper permission or specific subcommand permissions.

Syntax

/paper <subcommand> [arguments]

Subcommands

version

Display Paper server version information.

/paper version
/paper ver  # Alias

Permission: bukkit.command.paper.versionOutput includes:

Paper version and build number
Minecraft version
Git commit information
Previous version (if updated)

reload

Reload Paper configuration files without restarting the server.

/paper reload

Permission: bukkit.command.paper.reloadReloads:

config/paper-global.yml
config/paper-world-defaults.yml
Per-world configurations

Some settings require a full server restart. Reloading may not apply all changes and can cause issues in some cases.

heap

Generate a heap dump for memory analysis.

/paper heap

Permission: bukkit.command.paper.heapCreates a .hprof file in the server directory for analysis with tools like:

Eclipse Memory Analyzer (MAT)
VisualVM
JProfiler

Use this to diagnose memory leaks or high memory usage. The dump is created instantly and can be very large.

entity

Display entity information and statistics for the current world.

/paper entity

Permission: bukkit.command.paper.entityShows:

Entity count by type
Chunk locations with high entity counts
Entity distribution analysis

Useful for identifying:

Entity farms causing lag
Chunk errors with excessive entities
Mob spawner issues

mobcaps

Display current mob caps and spawn information.

/paper mobcaps
/paper playermobcaps  # Alias

Permission: bukkit.command.paper.mobcapsShows:

Current mob counts per category
Mob cap limits
Per-player mob counts (if per-player spawning is enabled)

Categories: MONSTER, CREATURE, AMBIENT, WATER_CREATURE, WATER_AMBIENT, UNDERGROUND_WATER_CREATURE, AXOLOTLS

dumpitem

Dump NBT data of the item you’re holding.

/paper dumpitem

Permission: bukkit.command.paper.dumpitemOutputs complete NBT data of the held item to console and provides a paste link. Useful for:

Plugin development
Custom item debugging
Understanding item data structure

dumpplugins

Dump information about all loaded plugins.

/paper dumpplugins

Permission: bukkit.command.paper.dumppluginsInformation includes:

Plugin name and version
Authors
Dependencies
Load order
Registered listeners
Commands
Permissions

Creates a detailed report for troubleshooting plugin conflicts.

dumplisteners

Dump all registered event listeners.

/paper dumplisteners

Permission: bukkit.command.paper.dumplistenersShows which plugins are listening to which events, useful for:

Identifying performance bottlenecks
Finding event conflicts
Debugging event-related issues

syncloadinfo

Display information about synchronous chunk loads.

/paper syncloadinfo

Permission: bukkit.command.paper.syncloadinfoShows:

Plugins causing synchronous chunk loads
Stack traces of sync load locations
Count of sync loads

Synchronous chunk loads cause server lag. This command helps identify problematic plugins.

Performance Monitoring

MSPT Command

Check server tick performance in milliseconds per tick.

/mspt

Permission: bukkit.command.mspt Output:

Current tick time
1-minute average
5-minute average
15-minute average

Understanding MSPT:

50ms = 20 TPS (target)
< 40ms = Excellent performance
40-45ms = Good performance
45-50ms = Acceptable
> 50ms = Server is lagging

Monitor MSPT during peak hours to identify performance issues. Consistent values over 50ms indicate you need to optimize or upgrade.

Timings

Generate detailed performance reports (legacy, but still available).

/timings on          # Start recording
/timings off         # Stop recording
/timings paste       # Upload and get report URL
/timings reset       # Clear recorded data

Permission: bukkit.command.timings

Timings adds overhead while recording. Use Spark profiler for modern performance analysis.

Vanilla Commands Enhanced

Paper enhances several vanilla commands:

Version Command

/version
/ver      # Alias
/about    # Alias

Shows Paper version, build info, and checks for updates.

Plugins Command

/plugins
/pl       # Alias

Lists all loaded plugins with Paper-specific formatting.

Chunk Management

While not Paper-specific, these vanilla commands are essential for administration:

Force Load Chunks

/forceload add <from> <to>
/forceload remove <from> <to>
/forceload query [<pos>]
/forceload remove all

Permission: minecraft.command.forceload Keep chunks loaded even when no players are nearby.

Force-loaded chunks consume resources continuously. Use sparingly.

World Management

Save Commands

/save-all [flush]     # Save all worlds
/save-off             # Disable auto-saving
/save-on              # Enable auto-saving

Permission: minecraft.command.save Options:

flush - Force write to disk immediately

When to use save-off

Disable auto-saving during:

Large WorldEdit operations
Backup creation
Mass chunk generation

Remember to run /save-on when finished!

Difficulty

/difficulty <difficulty>

Permission: minecraft.command.difficulty Options: peaceful, easy, normal, hard Changes take effect immediately without restart.

Permission Management

Op Commands

/op <player>          # Grant operator status
/deop <player>        # Revoke operator status

Permission: minecraft.command.op / minecraft.command.deop

Operator status grants all permissions. Use a permissions plugin (LuckPerms) for fine-grained control.

Whitelist

/whitelist add <player>
/whitelist remove <player>
/whitelist list
/whitelist on
/whitelist off
/whitelist reload

Permission: minecraft.command.whitelist

Player Management

Kick and Ban

/kick <player> [reason]
/ban <player> [reason]
/ban-ip <ip|player> [reason]
/pardon <player>
/pardon-ip <ip>
/banlist [ips|players]

Teleportation

/tp <player>                    # Teleport to player
/tp <player> <destination>      # Teleport player to destination
/tp <x> <y> <z>                # Teleport to coordinates

Debugging Commands

Debug

/debug start              # Start debug profiling
/debug stop              # Stop and save debug profile
/debug report            # Create debug report

Permission: minecraft.command.debug Creates .zip files with profiling data for Java VisualVM.

Perf

/perf start              # Start performance profiling
/perf stop               # Stop profiling

Permission: minecraft.command.perf Java Flight Recorder profiling (requires JFR-enabled JVM).

Server Control

Stop Server

/stop [reason]

Permission: minecraft.command.stop Gracefully shuts down the server:

Kicks all players with optional reason
Saves all worlds
Unloads all chunks
Stops the server

Restart (Script Required)

Paper doesn’t have a built-in /restart command. Use a server wrapper script:

#!/bin/bash
while true; do
    java -Xms10G -Xmx10G -jar paper.jar --nogui
    echo "Server restarting in 5 seconds..."
    sleep 5
done

Command Blocks

Paper provides additional configuration for command blocks (WorldConfiguration.java:561-566): config/paper-world-defaults.yml:

command-blocks:
  permissions-level: 2    # 1-4, controls what commands can run
  force-follow-perm-level: true

Permission Levels:

1 - Bypass spawn protection
2 - Use command blocks, /gamemode, /give
3 - Operator commands (/ban, /kick, etc.)
4 - All commands including /stop

Permissions Reference

All Paper command permissions follow the format:

bukkit.command.paper.<subcommand>

Default Permissions

Permission	Default	Description
`bukkit.command.paper`	op	Base Paper command
`bukkit.command.paper.version`	op	Version info
`bukkit.command.paper.reload`	op	Reload configs
`bukkit.command.paper.heap`	op	Create heap dump
`bukkit.command.paper.entity`	op	Entity info
`bukkit.command.paper.mobcaps`	op	Mob cap info
`bukkit.command.paper.dumpitem`	op	Dump item NBT
`bukkit.command.mspt`	op	View MSPT

All permissions default to OP. Configure with a permissions plugin for non-op access.

Command Tips

Monitoring Performance

Daily monitoring routine:

/mspt - Check current performance
/paper mobcaps - Verify mob spawning is healthy
/paper entity - Look for entity buildup
Review console for errors

When investigating lag:

/spark profiler --timeout 300 - 5-minute profile
/paper syncloadinfo - Check for sync chunk loads
/paper entity - Find entity hotspots

Development & Debugging

Useful for plugin developers:

/paper dumpitem          # Current item NBT
/paper dumpplugins       # Plugin details
/paper dumplisteners     # Event listeners
/minecraft:attribute     # Entity attributes
/data get entity         # Entity NBT

Maintenance Operations

Before making backups:

/save-off                # Disable auto-save
/save-all flush          # Force save all
# Create backup
/save-on                 # Re-enable auto-save

After updating Paper:

/version                 # Verify version
/paper reload            # Reload configs (if needed)

Performance Tuning

Optimize based on command output

Paper Config

Global configuration reference

World Config

Per-world settings

Overview

Getting Started

Server Administration

Core Concepts

Plugin Development

API Reference

Contributing

​Paper Commands

​Syntax

​Subcommands

​Performance Monitoring

​MSPT Command

​Timings

​Vanilla Commands Enhanced

​Version Command

​Plugins Command

​Chunk Management

​Force Load Chunks

​World Management

​Save Commands

​Difficulty

​Permission Management

​Op Commands

​Whitelist

​Player Management

​Kick and Ban

​Teleportation

​Debugging Commands

​Debug

​Perf

​Server Control

​Stop Server

​Restart (Script Required)

​Command Blocks

​Permissions Reference

​Default Permissions

​Command Tips

​Related Documentation

Performance Tuning

Paper Config

World Config

Build docs developers (and LLMs) love

Paper Commands

Syntax

Subcommands

Performance Monitoring

MSPT Command

Timings

Vanilla Commands Enhanced

Version Command

Plugins Command

Chunk Management

Force Load Chunks

World Management

Save Commands

Difficulty

Permission Management

Op Commands

Whitelist

Player Management

Kick and Ban

Teleportation

Debugging Commands

Debug

Perf

Server Control

Stop Server

Restart (Script Required)

Command Blocks

Permissions Reference

Default Permissions

Command Tips

Related Documentation