Cmdr

Cmdr is a fully extensible and type-safe command console designed for Roblox developers. It provides a robust framework for creating admin commands and integrating custom game systems via a command-line interface.

Key features include:

• Intelligent Autocompletion & Validation: Instant feedback and suggestions as users type.
• Security: Dual validation on both the client and server to ensure input integrity.
• Programmatic Execution: Ability to run commands on behalf of the local user via code.
• Input Binding: Bind commands directly to specific user inputs.
• Embedded Commands: Dynamically use the output of one command as an argument for another.

Hooks are callback functions used to tap into the command execution process. They are ideal for implementing permission systems, logging, or overriding command output.

Every hook receives a CommandContext, providing access to parsed arguments, execution context, and user metadata.

Registration Locations

• Server commands: Execute both client and server hooks.
• Client commands: Execute client hooks only.

Execution Logic

Hooks execute in order of priority (lowest to highest). If a hook returns a value that halts execution (like a string in BeforeRun), subsequent hooks in that phase will not run.

-- Example of a basic hook registration
registry:RegisterHook("BeforeRun", function(context)
	if context.Group == "DefaultAdmin" and context.Executor.UserId ~= game.CreatorId then
		return "You don't have permission to run this command"
	end
end)

The AutoExec feature allows you to define a list of command strings that run automatically the moment a command is registered. This is useful for setting up aliases, shortcuts, or initial state configurations without manual intervention.

Key Benefits:

• Encapsulated Setup: Keeps initialization logic bundled with the command definition.
• Automated Macros: Registers shortcuts as soon as a command becomes active.
• Order Independence: Commands in an AutoExec array are deferred to the end of the current frame cycle, ensuring all dependent commands are fully registered first.

:::warning Client-Only Execution AutoExec arrays only execute on the client. This prevents duplicate work on the server and protects performance. :::

AutoExec = {
	'alias "my-shortcut" my-command',
	'var= .my_setting true',
}

Cmdr provides two methods on the context object within a server-side command implementation to communicate with clients via network events:

• context:SendEvent(target, eventName, ...args): Dispatches a message to a specific client (e.g., a player).
• context:BroadcastEvent(eventName, ...args): Dispatches a message to every connected client.

When using user-generated text in these events, ensure you filter the content on the server using Roblox's TextService to comply with moderation requirements.

-- To a specific player
context:SendEvent(player, "ShowNotification", filteredTitle, filteredMessage, duration)

-- To everyone
context:BroadcastEvent("ShowNotification", filteredTitle, filteredMessage, duration)

You can define a Default function within a custom type. This function must return a string, as it is processed before parsing.

When a user executes a command, they can use a single period . to automatically substitute the argument with its defined default value. For example, if a command is kill <player> and the player type has a default of the command runner, the user can type kill ..

You can allow a single argument to accept multiple types by using prefixes. This is defined in the Type key of an argument within the Args section of a command definition. When a user provides an argument starting with a specific symbol, the command receives the value as the associated type.

Syntax Rules:

• Use a space between the symbol and the type (e.g., "string # number").
• You can chain as many prefixed types as needed (e.g., "string # number @ player % team").

Example: If Type = "string # number", providing #33 as the argument will result in the function receiving the number 33 instead of the string "#33".

-- Example of a prefixed union type definition
Type = "string # number"

When a command is executed, Cmdr follows this sequence (hooks are evaluated from lowest to highest priority within their respective phases):

1. BeforeRun hooks (Client)
2. Data function (Client)
3. ClientRun function (Client)
4. BeforeRun hooks (Server) *
5. Server command implementation *
6. AfterRun hooks (Server) *
7. AfterRun hooks (Client)

*Note: Server steps (4, 5, 6) only run if ClientRun is not present or returns nil.

WARNING

Never rely exclusively on client-side hooks (BeforeCommandRegister or client BeforeRun) for critical authorization. Always validate permissions on the server.

When customizing Cmdr, do not modify the Cmdr source code directly. Modifying the library or placing your custom commands inside Cmdr's BuiltInCommands folder will prevent you from receiving future updates easily.

Instead, use the provided API to customize behavior, register new commands, or implement hooks. If you find a missing feature or a bug, open an issue on GitHub rather than patching the source code.

Cmdr may not be suitable if:

• You need a pre-made admin suite: Cmdr provides core utility commands but does not include a massive library of moderation or 'fun' commands out of the box. You must implement your own or use the Cookbook.
• You are unfamiliar with Luau: Cmdr is developer-focused and requires writing your own command implementations, permission hooks, and custom systems (like logging) in Luau.
• Your primary audience is on Mobile or Console: Cmdr is keyboard-first. While functional on other platforms, mobile UI support is basic, and you will likely need to build custom UI toggles for touch or controller users.