Set up CommandNPC on Minecraft

CommandNPC runs commands when a player clicks a Citizens NPC. Use it for a shop NPC that opens a menu, a guide that sends players to a spawn, or a warp NPC that teleports them. It runs only on the server, so players install nothing.

Checked against CommandNPC 2.1.3, whose release notes say it updates the plugin to 1.19.3, with Citizens 2.0.44 build 4268, October 2026.

Read this first

Several unrelated plugins share the name CommandNPC. This guide covers the one by Bradydawg, which is on GitHub as Bradydawg/CommandNPC. It adds the /npc cmdadd command.

Its newest release is from December 2022 and targets 1.19.3. Citizens, the plugin it extends, is updated far more often. Its Spigot page lists Minecraft 1.7 to 1.19 as tested, and neither that page nor the release notes mention a newer version, so back up before you try it on one. If you want a version the author has tested, use the JAR Manager tab to pick one. Change your Minecraft version or mod loader shows how, and a version change reinstalls the server, so take a backup first.

What you need

• A Paper or Purpur server, which shows a Plugins tab under Content in the panel menu.
• Citizens 2. CommandNPC lists it as a required dependency and will not start without it.
• Vault and PlaceholderAPI are optional dependencies that CommandNPC lists. The price flag below charges a player only when Vault and an economy plugin that works with it are installed. Without them the price is ignored.

Install Citizens

Citizens is published on its SpigotMC page, and its Jenkins build server lists the builds at ci.citizensnpcs.co/job/Citizens2. The Plugins tab has no SpigotMC source, so upload the jar yourself:

1. On your computer, download the Citizens jar.
2. Open File Manager and go into the plugins folder.
3. Click Upload and choose the jar. The browser limit is 100 MB per file, and Citizens is about 4 MB.

Install CommandNPC

CommandNPC has a jar on its GitHub release page, so the GitHub button in the Plugins tab can install it. The button needs the file access permission on the server:

1. Open the Plugins tab and click GitHub.
2. Enter Bradydawg/CommandNPC, click Look up, then Next.
3. Pick the release listed as v2.1.3, which has the tag 2.1.3-alpha beside it, and click Next. The release has one jar, commandnpc-2.1.3.jar, so the panel skips the file choice and goes straight to the review step.
4. Click Install.
5. Open Console and click Restart. The server needs a restart before a new plugin loads.

If the GitHub button is not available to you, download commandnpc-2.1.3.jar from the GitHub releases page and upload it to plugins in File Manager. The first start creates plugins/CommandNPC/config.yml.

Add a command to an NPC

Run these in game. You need citizens.npc.create to make an NPC and commandnpc.admin to add commands to one.

1. Run /npc create Guide to make an NPC.
2. If you made it earlier, select it with /npc select <id or name>.
3. Run /npc cmdadd -c say %name clicked the guide. The -c flag runs the command from the console. %name is replaced by the name of the player who clicked.
4. Right-click the NPC to test it.

Commands you add are saved with the NPC. Flags that take a value, such as --v, start with two dashes.

Flags for /npc cmdadd

• -c runs the command through the console, and -o runs it as an operator.
• -r picks one random command from the NPC's list each time.
• --v <price> charges the player that amount first.
• --p <permission> requires the player to have that permission.
• --d <ticks> delays the command, and --cd <ticks> sets a cooldown. Twenty ticks is one second.
• --t <left|right|both> chooses which click triggers it. The default comes from config.yml.

Manage an NPC's commands

• /npc cmdinfo lists the commands on the selected NPC with their IDs.
• /npc cmdset <id> ... changes a command's flags.
• /npc cmdremove <id> removes one command, and /npc cmdreset removes them all.

Settings

When it first starts, CommandNPC writes its config.yml itself, filled with these defaults:

• ClickType: both sets which click triggers an NPC. The values are both, left and right.
• CoolDown: 20 is the pause, in ticks, before a player's next click on an NPC counts, to stop spam. Twenty ticks is one second.
• ExecuteCommandMessage: false stops the plugin sending a success message to the player after a command runs. Set it to true to turn the message on.
• BungeeCord: false is off by default. Set it to true to let commands such as server <name> send players to another server on a proxy.
• CooldownMessage: true tells a player who clicks too soon that they are cooling down.
• CheckForUpdates: true checks for updates and notifies you.

Open config.yml in File Manager, change a value and click Save, then run commandnpc reload in the Console to reload the plugin. The command needs commandnpc.admin or operator status, and the console counts as an operator.

Common problems

• Nothing happens when you click. Check that Citizens is in the Installed view and that the NPC is the selected one when you run /npc cmdinfo.
• The plugin does not load. Look in the Console for the first error. CommandNPC needs Citizens and was last released for 1.19.3.
• A flag is ignored. Flags with a value need two dashes, such as --cd 100.
• config.yml will not load. See How to find and fix YAML and JSON config errors.