Arguments & Suggestions

Commands can be made extremely flexible via arguments. Brigadier (And by proxy, the Commands API) uses the concept of a "Command tree," where each "branch" is its own "command". In a sense, arguments are just nested commands.

To create an argument, chain your LiteralNode with .then() to create a new branch in the Command Tree, and then call CommandDsl.argument() inside it. The first argument is the argument name, and the second is the ArgumentType.

// Snippet
LiteralNode root = CommandDsl.literal("money")
                .requires(PermissionChecks.permission("money.balance.self"))
                .executes(ctx -> {
                    ctx.getSource().getSender().sendPlainMessage("You have $xxx!"); // Do whatever you need to return the balance
                })
                .then(CommandDsl.argument("player", ArgumentTypes.player())
                    .requires(PermissionChecks.permission("money.balance.other"))
                    .executes(ctx -> {
                        final PlayerSelectorArgumentResolver targetResolver = ctx.getArgument("player", PlayerSelectorArgumentResolver.class);
                        final Player target = targetResolver.resolve(ctx.getSource()).getFirst();
                        ctx.getSource().getSender().sendPlainMessage("Player " + target.getName() + " has $xxx!");
                    })
                );

You may also chain .then() with for loops. This generates branches like:

/module chat <state>
/module guilds <state>
/module economy <state>

LiteralNode root = CommandDsl.literal("module");

List<String> modules = List.of("chat", "guilds", "economy");

for (String module : modules) {
    root.then(CommandDsl.literal(module)
            .then(CommandDsl.argument("state", StringArgumentType.word())
            .executes(ctx -> {
                String state = ctx.getArgument("state", String.class);
                return 1;
            })
        )
    );
}

.then() takes either a LiteralNode or an ArgumentNode, both of which are created by using CommandDsl. If you inspect them carefully, the inside of .then() looks exactly like a regular Brigadier command, and that's because it is!

When a player runs "/money" in-game and then presses the space bar to go to the next argument, the game will allow them to enter a Player. You'll notice that the argument's value is stored in the CommandContext<CommandSourceStack>. Argument resolution and types are beyond the scope of this guide, see Paper's documentation on Arguments and ArgumentTypes for more information.

Argument suggestions

You can suggest values for arguments to the player by using suggests(). These can be done explicitly or dynamically / programmatically.

The most basic way to suggest values for an argument is to use Suggest.fixed()

.suggests(Suggest.fixed("member", "officer", "leader"))

If you want to add tooltips to the suggestions (Text that displays when the player's mouse hovers over a suggested value), you can use Suggest.fixedWithTooltip()

// Assuming `MM` is MiniMessage
.suggests(Suggest.fixedWithTooltip(List.of(
    Suggest.suggestion("member", MM.deserialize("<gray>Default guild member</gray>")),
    Suggest.suggestion("officer", MM.deserialize("<yellow>Can manage invites</yellow>"))
)))

Suggestions may also be made dynamically using Suggest.dynamic(). Use Suggest.suggestion() to actually create the suggestion.

.suggests(Suggest.dynamic((ctx, remaining) ->
    rankService.getRanks().stream()
        .filter(rank -> rank.startsWith(remaining))
        .map(Suggest::suggestion)
        .toList()
))

.suggests(Suggest.dynamic((ctx, remaining) ->
    rankService.getRanks().stream()
        .filter(rank -> rank.startsWith(remaining))
        .map(rank -> Suggest.suggestion(
            rank,
            MM.deserialize("<gray>Rank:</gray> <yellow>" + rank + "</yellow>")
        ))
        .toList()
))

10 March 2026