Mojang Brigadier: a command parser and dispatcher for Java applications

What Brigadier is for, and who it is not for

Brigadier solves one problem: turning a line of text into a structured command call. The README describes it as a command parser and dispatcher designed and developed for Minecraft: Java Edition, and the repository is a Java library, not an application. There is no binary to run and no server to start.

The intended user is a Java developer who already has a program with a notion of a caller. That caller is represented by a type parameter, written as <S> throughout the documentation, and the README calls it "any custom object you choose to identify a command source". In Minecraft that object carries the player or console that issued the command. In your own program it might be a session, a user record or a test harness.

That design decision is also the boundary. Brigadier assumes commands arrive as a string that you hand to it, and it assumes you will build the tree of valid commands yourself. If you want a framework that discovers commands, parses flags from the process arguments and prints help without you writing any of it, Brigadier is the wrong layer. It gives you the parser and the dispatcher; everything above that is yours.

The command tree, argument types and the two-step parse

A dispatcher holds a command tree made of CommandNode objects. The README states that the root node must have LiteralCommandNode children, so the first token of any command is a fixed string you register. Below a literal you can attach either another literal or an ArgumentCommandNode, which pairs a name with an argument type.

Argument types do the parsing. The README explains that an argument type is asked to parse as much input as it can, then stores the result or throws a relevant error. Its example is an integer argument that turns "123" into the int 123 and rejects "onetwothree". Brigadier ships standard types such as IntegerArgumentType, and the README encourages writing your own for integration into your own product.

Execution is split into two calls. dispatcher.execute("foo 123", source) parses and runs in one step and returns an int, which the README says is typically not useful to programmers. The alternative is dispatcher.parse("foo 123", source) followed by execute(parse). The README calls this split "highly recommended" because the parse step is the most expensive and can be cached. That is the mechanism worth understanding: parsing produces a ParseResults<S> that you can inspect or reuse, and the README notes that the parse itself never fails. Instead, ParseResults carries a possible context plus a map of parse exceptions keyed by the nodes it encountered, so a failed parse is data you can read rather than an exception thrown in your face. CommandSyntaxException is what you get from the one-step execute path when the input does not fit the tree.

Registration is append-only. The README says every registration is an append operation, so a downstream project can extend commands without touching the source that created them. That matters if you ship a plugin surface.

Installing Brigadier from libraries.minecraft.net

The README gives one distribution channel: Maven and Gradle via libraries.minecraft.net, with group com.mojang and artifact name brigadier. There is no download page and no CLI installer, so installation means adding a repository and a dependency to your build file. The README instructs you to replace the version placeholder with the latest version, and does not state what that version is.

For Gradle, add the repository and the dependency. The README shows the older compile configuration:

maven {
    url "https://libraries.minecraft.net"
}

compile 'com.mojang:brigadier:(the latest version)'

For Maven, the same two pieces. The repository element goes in your POM, and the dependency names the group, artifact and version:

<repository>
  <id>minecraft-libraries</id>
  <name>Minecraft Libraries</name>
  <url>https://libraries.minecraft.net</url>
</repository>

<dependency>
    <groupId>com.mojang</groupId>
    <artifactId>brigadier</artifactId>
    <version>(the latest version)</version>
</dependency>

A first real use is the example the README provides. It registers two commands, foo and foo <bar>, on a dispatcher whose source type is CommandSourceStack:

CommandDispatcher<CommandSourceStack> dispatcher = new CommandDispatcher<>();

dispatcher.register(
    literal("foo")
        .then(
            argument("bar", integer())
                .executes(c -> {
                    System.out.println("Bar is " + getInteger(c, "bar"));
                    return 1;
                })
        )
        .executes(c -> {
            System.out.println("Called foo with no arguments");
            return 1;
        })
);

If you run that and call dispatcher.execute("foo 123", source), you should see the bar value printed. Call it with just "foo" and the second executes block runs instead. The README does not include the imports for literal, argument, integer or getInteger, so expect to resolve those yourself.

Usage strings, permissions and what Brigadier will not do for you

Two methods produce human-readable command descriptions, and both need a target node. getAllUsage(node, source, restricted) returns every executable end point under that node with its readable path, and the README shows the shape as [`foo`, `foo <bar>`]. When restricted is true it skips commands the source cannot access. getSmartUsage(node, source) is described as returning something shorter, and the README text cuts off mid-sentence, so the exact behaviour of the smart form is not documented in the repository README.

The permission check is the interesting part. Brigadier does not decide who may run what. It asks whether the source has access, which means you supply that answer, typically through a requirement predicate on a node. The library's contribution is that it will not offer or execute a command the source is denied.

What it will not do is equally clear. It does not read process arguments, does not format output for a terminal, does not ship a REPL and does not persist anything. The README also notes that a RuntimeException can bubble out of execute if your command does not handle it, so the dispatcher is not a sandbox around your own code. And because parsing is the expensive step that the README recommends caching, a hot path that re-parses the same input on every call is leaving the library's main advantage unused.

Where Brigadier is the wrong choice

The clearest failure mode is a non-Java program. Brigadier is a Java library distributed as a Maven artifact, and the README offers no bindings, no command-line binary and no other language package. If your service is written in Go, Rust or Python, nothing in this repository helps you.

A second case is a program whose interface is a handful of fixed flags. Brigadier's value comes from a tree with nested literals, typed arguments and permissions. Building that tree for two options is more code than reading the arguments directly, and you gain a parse cache you will never use.

The third case is a project that wants a complete CLI product. Brigadier gives you parsing and dispatch. Help text, shell completion, configuration files and subcommand discovery are all outside the README's scope. If you adopt it expecting those, you will be writing them yourself, and the README's own examples of usage strings are the only help format it offers.

There is also a versioning caveat. The most recent release listed in the repository is 1.0.18, tagged 2021-07-16, and the README tells you to substitute the latest version rather than naming one. The last push to the repository was on 2026-07-17, so the source sees activity while the tagged releases do not.

How Brigadier differs from a general-purpose CLI library

The natural alternative is a general-purpose Java CLI library such as picocli, which is built around annotations and the process entry point. The difference in approach is where the command definition lives. picocli derives commands from annotated classes and methods and wires them to main(String[]), so the command surface is your Java API. Brigadier inverts that: you construct a tree of nodes at runtime, and the tree is the source of truth. Nothing is discovered by reflection.

That inversion is what makes Brigadier suitable for a game console or a server console where commands are registered from many places, including plugins loaded after startup. The README's append-only registration rule exists precisely for that. A CLI library that binds one class to one program entry point has no equivalent, and a Brigadier tree can be extended by code that never saw the original command definitions.

The cost is that you write the registration code by hand. There are no annotations to reduce it, and the README's own example is a builder chain rather than a declaration. The other practical difference is the parse cache: Brigadier's parse and execute split is designed so the same input can be parsed once and dispatched many times, which a per-invocation CLI parser does not offer because it only ever sees one invocation.

Licence, maintenance and upgrade cost

Brigadier is MIT licensed, and the README states it is freely available for use elsewhere under that licence. MIT is permissive, so the practical implication is that you can bundle the library in a closed product provided you keep the copyright notice and licence text with it. That is a description of the licence terms, not legal advice; read the LICENSE file in the repository for the operative text.

Contributing is a separate matter. The README says most contributions require a Contributor License Agreement granting Microsoft the rights to use the contribution, and the project follows the Microsoft Open Source Code of Conduct. If you plan to send patches, that agreement is part of the process.

The upgrade cost is low by design. The public surface described in the README is a dispatcher, nodes, argument types and two usage methods, and the release history shows long gaps between tags: 1.0.15 in 2018, 1.0.17 in 2019 and 1.0.18 in 2021. A library that changes this slowly is unlikely to break your build on a minor bump, but it also means fixes arrive on that same rhythm. The repository's last push was on 2026-07-17, which is separate from the release cadence and does not by itself tell you what shipped.

Editorial conclusion

Adopt Brigadier when you are writing a Java application that needs a command tree, typed arguments and a parse step you can cache, and when you are willing to register every command yourself. Do not adopt it for a shell script, a non-Java service or a project that wants a ready-made CLI front end. Before you start, verify the current version on libraries.minecraft.net, since the README tells you to replace the version placeholder and the last tagged release in the repository is 1.0.18 from 2021-07-16.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mojang/brigadier on GitHub
4. README
5. Releases