Mattermost mmctl for coding agents

A coding agent with shell access can run Mattermost’s mmctl command-line tool to read workspace information and perform administrative tasks. The tool sends commands to a Mattermost server through a local connection or the server’s remote API, an interface for sending requests over a network. For example, an agent can list users and return the result as JSON, a structured format that code can parse.

An agent can list users without changing data. Sign in outside the agent prompt, then let the agent run the query. The commands are based on published documentation and have not been installed or tested for this article.

Set up mmctl

The mmctl documentation describes mmctl as a CLI tool for the Mattermost server that is installed locally and uses the Mattermost API. It also works with a remote server. mmctl comes bundled with Mattermost and sits in the bin folder of the installation. To install it on another machine, the documentation recommends the release download for your version and platform. For example, this downloads version v10.7.0 for 64-bit Linux:

curl -vfsSL -O https://releases.mattermost.com/mmctl/v10.7.0/linux_amd64.tar

Replace the version with the one your server runs, then unpack the archive and put mmctl on your PATH. On Linux and macOS, brew install mmctl also works, but the documentation says the Homebrew package is maintained by the community and is not an officially supported method.

The download only installs the tool. It does not connect to your workspace or authenticate you. Before running commands against a server, sign in from a trusted terminal:

mmctl auth login https://mattermost.example.com

When you leave out the other flags, mmctl asks for the missing values, such as your username and password. You can also sign in with a personal access token read from a file with --access-token-file, and --mfa-token passes a multi-factor authentication code. mmctl stores the credentials in its configuration file, by default $XDG_CONFIG_HOME/mmctl/config. Enter your Mattermost credentials and any required multi-factor authentication code in a trusted terminal, not in the agent’s prompt.

On a self-hosted server, mmctl also has a local mode. It talks to the server through a Unix socket on the same machine and needs no user account, because the server treats requests from the socket as authorized. Local mode has to be turned on in the server configuration. From Mattermost v10.8, mmctl uses local mode on its own when it finds no stored credentials. So think carefully before you let an agent run mmctl on the server itself.

List users as a read-only task

After a person signs in with mmctl, an agent can request a user list in JSON:

mmctl user list --all --json

user list retrieves Mattermost user information. --json formats the results so scripts or the agent can read them. Without --all, the command returns one page of 200 users, so a larger workspace would look incomplete. The user list reference also documents filters, for example --active or --team. The account used to sign in must have permission to list users.

For example, a coding agent could compare the returned roster with a list of expected accounts in a repository, then report which names need human review. The agent compares the returned accounts with a local file on your computer. The mmctl user list request contacts the Mattermost server. The listing itself does not change server data. Avoid copying the full result into logs or prompts when user details are not needed.

A realistic agent prompt is:

Run mmctl user list --all --json using the existing authenticated session. Compare the returned accounts with expected-users.txt. Report accounts that appear in only one source, and do not change Mattermost data.

The prompt tells the agent to read data only, includes no credentials, and explicitly forbids data changes.

Keep administrative writes separate

mmctl also supports commands that change workspace data. For example, mmctl user deactivate logs a user out of all sessions and blocks new logins. mmctl user delete and mmctl channel delete permanently delete a user or a channel, together with related information such as posts. Without the --confirm flag they ask for confirmation first, and an agent could pass that flag. They only work when the server allows deletion through the API. An agent should not run those commands after comparing rosters. A person should review any discrepancy and authorize changes separately.

mmctl uses the permissions of the account that signed in. Even when you enter a command in a local shell, mmctl can send a request to a remote workspace and change its data. Keep the example task read-only. Before giving an agent broader access, check the documentation for the exact commands and required permissions.