Command Line Tools

From the directory where the Mattermost server is installed, a mattermost command is available for configuring the system. For an overview of the Mattermost command line interface (CLI), read this article from Santos.

These mattermost commands include:

General Administration

  • Creating teams
  • Creating users
  • Assigning roles to users
  • Resetting user passwords
  • Inviting users to teams

Advanced Administration

  • Permanently deleting users (use cautiously - database backup recommended before use)
  • Permanently deleting teams (use cautiously - database backup recommended before use)

Advanced Automation

  • Creating channels
  • Inviting users to channels
  • Removing users from channels
  • Listing all channels for a team
  • Restoring previously deleted channels
  • Modifying a channel’s public/private type
  • Migrating sign-in options
  • Resetting multi-factor authentication for a user
  • Creating sample data

Diagnostics

  • Analyzing the database for relational consistency

Using the CLI

To run the CLI commands, you must be in the directory that contains the Mattermost executable. On a default install of Mattermost, the directory is /opt/mattermost/bin. Also, if you followed our installation process, you must run the commands as the user mattermost. The name of the executable is mattermost.

For example, to get the Mattermost version on a default installation of Mattermost:

cd /opt/mattermost/bin
./mattermost version

Using the CLI on GitLab Omnibus

On GitLab Omnibus, you must be in the following directory when you run CLI commands: /opt/gitlab/embedded/service/mattermost. Also, you must run the commands as the user mattermost and specify the location of the configuration file. The executable is /opt/gitlab/embedded/bin/mattermost.

For example, to get the Mattermost version on GitLab Omnibus:

cd /opt/gitlab/embedded/service/mattermost
sudo -u mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json version

Note

The example commands in the documentation are for a default installation of Mattermost. You must modify the commands so that they work on GitLab Omnibus.

Using the CLI on Docker Install

On Docker install, the /mattermost/bin directory was added to PATH, so you can use the CLI directly with the docker exec command. Note that the container name may be mattermostdocker_app_1 if you installed Mattermost with docker-compose.yml.

For example, to get the Mattermost version on a Docker install:

docker exec -it <your-mattermost-container-name> mattermost version

Using the CLI on Docker Preview

The preceding documentation and command reference below also applies to the Mattermost docker preview image.

Mattermost 3.6 and later

The new CLI tool is supported in Mattermost 3.6 and later. To see available commands in the old CLI tool, see Mattermost 3.5 and earlier.

Note

For Mattermost 4.10 and earlier, the commands used the platform executable instead of mattermost. For example, to check the Mattermost version, one would run ./platform version instead of ./mattermost version.

Notes:

  • Parameters in CLI commands are order-specific.
  • If special characters (!, |, (, ), \, ', and ") are used, the entire argument needs to be surrounded by single quotes (e.g. -password 'mypassword!', or the individual characters need to be escaped out (e.g. -password mypassword\!).
  • Team name and channel name refer to the handles, not the display names. So in the url https://community.mattermost.com/core/channels/town-square team name would be core and channel name would be town-square

Tip

If you automate user creation through the CLI tool with SMTP enabled, emails will be sent to all new users created. If you run such a load script, it is best to disable SMTP or to use test accounts so that new account creation emails aren’t unintentionally sent to people at your organization who aren’t expecting them.

mattermost

Description
Commands for configuring and managing your Mattermost instance and users.
Options
-c, --config {string}   Configuration file to use. (default "config.json")
--disableconfigwatch {boolean}  When true, the config.json file will not be reloaded automatically when another process changes it (default "false")
Child Commands

mattermost channel

Description
Commands for channel management.
Child Commands

Note

{channel} value

For the add, archive, delete, remove and restore commands, you can specfiy the {channels} value by {team}:{channel} using the team and channel URLs, or by using channel IDs. For example, in the following URL the {channels} value is myteam:mychannel:

https://example.com/myteam/channels/mychannel

Also, the team and channel names in the URL should be written in lowercase.

mattermost channel add

Description
Add users to a channel. If adding multiple users, use a space-separated list.
Format
mattermost channel add {channel} {users}
Examples
./mattermost channel add 8soyabwthjnf9qibfztje5a36h user@example.com username
./mattermost channel add myteam:mychannel user@example.com username

mattermost channel archive

Description
Archive a channel. Archived channels are not accessible to users, but remain in the database. To restore a channel from the archive, see mattermost channel restore. Channels can be specified by {team}:{channel} using the team and channel names, or by using channel IDs.
Format
mattermost channel archive {channels}
Examples
./mattermost channel archive 8soyabwthjnf9qibfztje5a36h
./mattermost channel archive myteam:mychannel

mattermost channel create

Description
Create a channel.
Format
mattermost channel create
Examples
./mattermost channel create --team myteam --name mynewchannel --display_name "My New Channel"
./mattermost channel create --team myteam --name mynewprivatechannel --display_name "My New Private Channel" --private
Options
--display_name string   Channel Display Name
--header string         Channel header
--name string           Channel Name
--private               Create a private channel.
--purpose string        Channel purpose
--team string           Team name or ID

mattermost channel delete

Description
Permanently delete a channel along with all related information, including posts from the database. Channels can be specified by {team}:{channel} using the team and channel names, or by using channel IDs.
Format
mattermost channel delete {channels}
Examples
./mattermost channel delete 8soyabwthjnf9qibfztje5a36h
./mattermost channel delete myteam:mychannel

mattermost channel list

Description
List all channels on a specified team. Private channels are appended with (private) and archived channels are appended with (archived).
Format
mattermost channel list {teams}
Example
./mattermost channel list myteam

mattermost channel modify

Description
Modify a channel’s public/private type.
Format
mattermost channel modify
Example
./mattermost channel modify myteam:mychannel --username myusername --private
Options
--username [REQUIRED] Username of the user who is changing the channel privacy.
--public   Change a private channel to be public.
--private  Change a public channel to be private.

mattermost channel move

Description
Move channels to another team. The command validates that all users in the channel belong to the target team. Incoming/Outgoing webhooks are moved along with the channel. Channels can be specified by [team]:[channel] or by using channel IDs.
Format
mattermost channel move
Example
./mattermost channel move newteam 8soyabwthjnf9qibfztje5a36h --username myusername
./mattermost channel move newteam myteam:mychannel --username myusername
Options
--username [REQUIRED] Username of the user who is moving the team.

mattermost channel remove

Description
Remove users from a channel.
Format
mattermost channel remove {channel} {users}
Examples
./mattermost channel remove 8soyabwthjnf9qibfztje5a36h user@example.com username
./mattermost channel remove myteam:mychannel user@example.com username
./mattermost channel remove myteam:mychannel --all-users
Options
--all-users string     Remove all users from the channel.

mattermost channel rename

Description
Rename a channel. Channels can be specified by {team}:{channel} using the team and channel names, or by using channel IDs.
Format
mattermost channel rename {channel} newchannelname --display_name "New Display Name"
Examples
./mattermost channel rename 8soyabwthjnf9qibfztje5a36h newchannelname --display_name "New Display Name"
./mattermost channel rename myteam:mychannel newchannelname --display_name "New Display Name"
Options
--display_name string   Channel Display Name

mattermost channel restore

Description
Restore a channel from the archive. Channels can be specified by {team}:{channel} using the team and channel names, or by using channel IDs.
Format
mattermost channel restore {channels}
Examples
./mattermost channel restore 8soyabwthjnf9qibfztje5a36h
./mattermost channel restore myteam:mychannel

mattermost command

Description
Commands for slash command management.
Child Commands

mattermost command create

Description
Create a custom slash command for a specified team.
Format
mattermost command create
Examples
./mattermost command create myteam --title MyCommand --description "My Command Description" --trigger-word mycommand --url http://localhost:8000/my-slash-handler --creator myusername --response-username my-bot-username --icon http://localhost:8000/my-slash-handler-bot-icon.png --autocomplete --post
Options
--title string                     Command Title
--description string               Command Description
--trigger-word string [REQUIRED]   Command Trigger Word
--url  string   [REQUIRED]         Command Callback URL
--creator string  [REQUIRED]       Command Creator's Username
--response-username string         Command Response Username
--icon string                      Command icon URL
--autocomplete bool                Show command in autocomplete list
--autocompleteDesc string          Short command description for autocomplete list
--autocompleteHint string          Command arguments displayed as help in autocomplete list
--post bool                        Use POST method for callback URL

mattermost command delete

Description
Delete a slash command. Commands can be specified by command ID.
Format
mattermost command delete {commandID}
Examples
./mattermost command delete commandID

mattermost command list

Description
List all commands on specified teams or all teams by default.
Format
mattermost command list {team}
Examples
./mattermost command list myteam

mattermost command modify

Description
Modify a slash command. Commands can be specified by command ID.

Note

Only fields that you want to modify need to be specified. Also, when modifying the command’s creator, the new creator specified must have the permission to create commands.
Format
mattermost command modify {commandID}
Examples
./mattermost command modify commandID --title MyModifiedCommand --description "My Modified Command Description" --trigger-word mycommand --url http://localhost:8000/my-slash-handler --creator myusername --response-username my-bot-username --icon http://localhost:8000/my-slash-handler-bot-icon.png --autocomplete --post
Options
--title string                     Command Title
--description string               Command Description
--trigger-word string              Command Trigger Word
--url  string                      Command Callback URL
--creator string                   Command Creator's Username
--response-username string         Command Response Username
--icon string                      Command Icon URL
--autocomplete bool                Show command in autocomplete list
--autocompleteDesc string          Short command description for autocomplete list
--autocompleteHint string          Command arguments displayed as help in autocomplete list
--post bool                        Use POST method for callback URL, else use GET method

mattermost command move

Description
Move a slash command to a different team. Commands can be specified by {team}:{command-trigger-word}, or by using command IDs.
Format
mattermost command move
Examples
./mattermost command move newteam oldteam:command-trigger-word
./mattermost command move newteam o8soyabwthjnf9qibfztje5a36h

mattermost command show

Description
Show a custom slash command. Commands can be specified by command ID. Returns command ID, team ID, trigger word, display name and creator username.
Format
command show {commandID}
Examples
./mattermost command show commandID

mattermost config

Description
Commands for managing the configuration file.
Child Command

mattermost config get

Description
Retrieve the value of a config setting by its name in dot notation.
Format
mattermost config get {config.name}
Examples
./mattermost config get SqlSettings.DriverName
Options
--path string  Optional subpath; defaults to value in Site URL.

mattermost config migrate

Description
Migrate a file-based configuration to (or from) a database-based configuration. Point the Mattermost server at the target configuration to start using it. If using SAML, ensure the SAML certificates and keys are accessible to also migrate into the database.

Note

If a from parameter is not specified, the command will fall back to what is specified in –config.
Format
mattermost config migrate {config to read} {config to write}
Examples
./mattermost config migrate  path/to/config.json "postgres://mmuser:mostest@dockerhost:5432/mattermost_test?sslmode=disable&connect_timeout=10"

mattermost config set

Description
Set the value of a config setting by its name in dot notation. Accepts multiple values for array settings.
Format
mattermost config set {config.name} {setting new value}
Examples
./mattermost config set SqlSettings.DriverName mysql
Options
--path string  Optional subpath; defaults to value in Site URL.

mattermost config show

Description
Print the current mattermost configuration in an easy to read format.
Format
mattermost config show
Examples
./mattermost config show

mattermost config validate

Description

Makes sure the configuration file has the following properties:

  • Is valid JSON.
  • Has attributes of the correct type, such as bool, int, and str.
  • All entries are valid. For example, checks that entries are below the maximum length.
Format
mattermost config validate
Example
./mattermost config validate

mattermost export

Description
Commands for exporting data for compliance and for merging multiple Mattermost instances.
Child Commands

mattermost export actiance

Description
Export data from Mattermost in Actiance XML format.
Format
mattermost export actiance
Example
./mattermost export actiance --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (milliseconds since epoch, UTC) to export data from.

mattermost export bulk

Description
Export data to a file compatible with the Mattermost Bulk Import format.
Format
mattermost export bulk
Example
./mattermost export bulk file.json --all-teams
Options
--all-teams bool [REQUIRED]  Export all teams from the server.

mattermost export csv

Description
Export data from Mattermost in CSV format.
Format
mattermost export csv
Example
./mattermost export csv --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (seconds since epoch, UTC) to export data from.

mattermost export global-relay-zip

Description
Export data from Mattermost into a zip file containing emails to send to Global Relay for debug and testing purposes only. This does not archive any information in Global Relay.
Format
mattermost export global-relay-zip
Example
./mattermost export global-relay-zip --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (seconds since epoch, UTC) to export data from.

mattermost export schedule

Description
Schedule an export job in a format suitable for importing into a third-party archive system.
Format
mattermost export schedule
Example
./mattermost export schedule --format=actiance --exportFrom=1513102632
Options
--format string         Output file format. Currently, only ``actiance`` is supported.
--exportFrom string     Unix timestamp (seconds since epoch, UTC) to export data from.
--timeoutSeconds string Set how long the export should run for before timing out.

mattermost group

Description
Commands for managing Mattermost groups. For more information on Mattermost groups please see this documentation.
Child Commands

mattermost group channel

Description
Commands for managing Mattermost groups linked to a channel.
Child Commands

mattermost group channel enable

Description
Enables group constraint on the specified channel. When a channel is group constrained, channel membership is managed by linked groups instead of managed by manually adding and removing users.

Note

To enable a group constraint on a specific channel, you must already have at least one group associated. See AD/LDAP Group documentation for more details on how to associate a group to a channel.

Format
mattermost group channel enable {team}:{channel}
Examples
./mattermost group channel enable myteam:mychannel

mattermost group channel disable

Description
Disables group constraint on the specified channel.
Format
mattermost group channel disable {team}:{channel}
Examples
./mattermost group channel disable myteam:mychannel

mattermost group channel list

Description
Lists the groups associated with a channel.
Format
mattermost group channel list {team}:{channel}
Examples
./mattermost group channel list myteam:mychannel

mattermost group channel status

Description
Shows the group constraint status of the specified channel. Returns “Enabled” when channel membership is managed by linked groups. Returns “Disabled” when the channel membership is managed by manually adding and removing users.
Format
mattermost group channel status {team}:{channel}
Examples
./mattermost group channel status myteam:mychannel

mattermost group team

Description
Commands for managing Mattermost groups linked to a team.
Child Commands

mattermost group team enable

Description
Enables group constraint on the specified team. When a team is group constrained, team membership is managed by linked groups instead of managed by manually inviting and removing users.

Note

To enable a group constraint on a specific team, you must already have at least one group associated. See AD/LDAP Group documentation for more details on how to associate a group to a team.

Format
mattermost group team enable {team}
Examples
./mattermost group team enable myteam

mattermost group team disable

Description
Disables group constraint on the specified team.
Format
mattermost group team disable {team}
Examples
./mattermost group team disable myteam

mattermost group team list

Description
Lists the groups associated with a team.
Format
mattermost group team list {team}
Examples
./mattermost group team list myteam

mattermost group team status

Description
Shows the group constraint status of the specified team. Returns “Enabled” when team membership is managed by linked groups. Returns “Disabled” when the team membership is managed by manually inviting and removing users.
Format
mattermost group team status {team}
Examples
./mattermost group team status myteam

mattermost help

Description
Generate full documentation in Markdown format for the Mattermost command line tools.
Format
mattermost help {outputdir}

mattermost import

Description
Import data into Mattermost.
Child Command

mattermost import bulk

Description
Import data from a Mattermost Bulk Import File.
Format
mattermost import bulk {file}
Options
--apply         Save the import data to the database. Use with caution - this cannot be reverted.
--validate      Validate the import data without making any changes to the system.
--workers int   How many workers to run whilst doing the import. (default 2)
Example
./mattermost import bulk bulk-file.jsonl

mattermost import slack

Description
Import a team from a Slack export zip file.
Format
mattermost import slack {team} {file}
Example
./mattermost import slack myteam slack_export.zip

mattermost integrity

Description
Check database schema integrity as well as referential integrity of channels, slash commands, webhooks, posts, schemes, sessions, users, and teams. This process may temporarily affect live system performance, and should be used during off-peak periods.
Format
mattermost integrity
Example
./mattermost integrity --confirm --verbose
Options
--confirm   Optional. Skip the confirmation message which indicates that the complete integrity check may temporarily harm system performance. This is not recommended in production environments.
--verbose   Outputs a detailed report of number and type of orphaned records including ids (if any).

mattermost jobserver

Description
Start the Mattermost job server.
Format
mattermost jobserver
Example
./mattermost jobserver

mattermost ldap

Description
Commands to configure and synchronize AD/LDAP.
Child Command

mattermost ldap idmigrate

Description

Migrate LDAP Id Attribute to new value.

Run this utility to change the value of your ID Attribute without your users losing their accounts. After running the command you can change the ID Attribute to the new value in your config.json. For example, if your current ID Attribute was sAMAccountName and you wanted to change it to objectGUID, you would:

  1. Wait for an off-peak time when your users won’t be impacted by a server restart.
  2. Run the command mattermost ldap idmigrate objectGUID.
  3. Edit your config.json and change your IdAttribute field to the new value objectGUID.
  4. Restart the Mattermost server.
Format
mattermost ldap idmigrate {attribute}
Example
./mattermost ldap idmigrate objectGUID

mattermost ldap sync

Description
Synchronize all AD/LDAP users now.
Format
mattermost ldap sync
Example
./mattermost ldap sync

mattermost license

Description
Commands to manage licensing.
Child Command

mattermost license upload

Description
Upload a license. This command replaces the current license if one is already uploaded.
Format
mattermost license upload {license}
Example
./mattermost license upload /path/to/license/mylicensefile.mattermost-license

Note

The Mattermost server needs to be restarted after uploading a license file for any changes to take effect. Also, for cluster setups the license file needs to be uploaded to every node.

mattermost logs

Description
Displays Mattermost logs in a human-readable format.
Format
mattermost logs
Example
./mattermost logs --logrus
Options
--logrus   Displays Mattermost logs in `logrus format <https://github.com/sirupsen/logrus>`_. Else, standard output is returned.

mattermost permissions

Description
Commands to manage advanced permissions.
Child Commands

mattermost permissions export

Description
Prints to stdout a jsonl representation of Schemes and Roles from a Mattermost instance. Used to export Roles and Schemes from one Mattermost instance to another. The output is a jsonl representation with each line containing a json representation of a Scheme and its associated Roles. The output is intended to be used as the input of mattermost permissions import.
Format
mattermost permissions export
Example
./mattermost permissions export > my-permissions-export.jsonl

mattermost permissions import

Description
Creates Roles and Schemes on a Mattermost instance from a jsonl input file in the format outputted by mattermost permissions export.
Format
mattermost permissions import {file}
Example
./mattermost permissions import my-permissions-export.jsonl

mattermost permissions reset

Description
Reset permissions for all users, including Admins, to their default state on new installs. Note: this will delete all custom schemes.
Format
mattermost permissions reset
Example
./mattermost permissions reset
Options
--confirm   Confirm you really want to reset the permissions system and a DB backup has been performed.

mattermost plugin

Description
Commands to manage plugins.
Child Commands

mattermost plugin add

Description
Add plugins to your Mattermost server. If adding multiple plugins, use a space-separated list.
Format
mattermost plugin add {plugin tar file}
Example
./mattermost plugin add hovercardexample.tar.gz pluginexample.tar.gz

mattermost plugin delete

Description
Delete previously uploaded plugins from your Mattermost server. If deleting multiple plugins, use a space-separated list.
Format
mattermost plugin delete {plugin_id}
Example
./mattermost plugin delete hovercardexample pluginexample

mattermost plugin disable

Description
Disable plugins. Disabled plugins are immediately removed from the user interface and logged out of all sessions. If disabling multiple plugins, use a space-separated list.
Format
mattermost plugin disable {plugin_id}
Example
./mattermost plugin disable hovercardexample pluginexample

mattermost plugin enable

Description
Enable plugins for use on your Mattermost server. If enabling multiple plugins, use a space-separated list.
Format
mattermost plugin enable {plugin_id}
Example
./mattermost plugin enable hovercardexample pluginexample

mattermost plugin list

Description
List all active and inactive plugins installed on your Mattermost server.
Format
mattermost plugin list
Example
./mattermost plugin list

mattermost reset

Description
Completely erase the database causing the loss of all data. This resets Mattermost to its initial state.
Format
mattermost reset
Options
--confirm   Confirm you really want to delete everything and a DB backup has been performed.

mattermost roles

Description
Commands to manage user roles.
Child Commands

mattermost roles member

Description
Remove system admin privileges from a user.
Format
mattermost roles member {users}
Example
./mattermost roles member user1

mattermost roles system_admin

Description
Promote a user to a System Admin.
Format
mattermost roles system_admin {users}
Example
./mattermost roles system_admin user1

mattermost sampledata

Description

New in version 4.7: Generate sample data and populate the Mattermost database. Supported in Mattermost v4.7 and later.

The command generates one user as the System Administrator with a username sysadmin and password Sys@dmin-sample1. Other users are generated following an index, e.g. with username user-1 and password SampleUs@r-1.

Format
mattermost sampledata
Example
./mattermost sampledata --seed 10 --teams 4 --users 30
Options
-u, --users int                      The number of sample users. (default 15)
    --profile-images string          Optional. Path to folder with images to randomly pick as user profile image.
-t, --teams int                      The number of sample teams. (default 2)
    --team-memberships int           The number of sample team memberships per user. (default 2)
    --channels-per-team int          The number of sample channels per team. (default 10)
    --channel-memberships int        The number of sample channel memberships per user in a team. (default 5)
    --posts-per-channel int          The number of sample post per channel. (default 100)
    --direct-channels int            The number of sample direct message channels. (default 30)
    --group-channels int             The number of sample group message channels. (default 15)
    --posts-per-direct-channel int   The number of sample posts per direct message channel. (default 15)
    --posts-per-group-channel int    The number of sample post per group message channel. (default 30)
-s, --seed int                       Seed used for generating the random data (Different seeds generate different data). (default 1)
-b, --bulk string                    Optional. Path to write a JSONL bulk file instead of loading into the database.
-w, --workers int                    How many workers to run during the import. (default 2)

mattermost server

Description
Runs the Mattermost server.
Format
mattermost server

mattermost team

Description
Commands to manage teams.
Child Commands

Note

{team-name} value

For the add, delete, and remove commands, you can determine the {team-name} value from the URLs that you use to access your instance of Mattermost. For example, in the following URL the {team-name} value is myteam:

https://example.com/myteam/channels/mychannel

Also, the team and channel names in the URL should be written in lowercase.

mattermost team add

Description
Add users to a team. Before running this command, see the note about {team-name}.
Format
mattermost team add {team-name} {users}
Example
./mattermost team add myteam user@example.com username

mattermost team archive

Description
Archive teams based on name. Before running this command, see the note about {team-name}.
Format
mattermost team archive {team}
Examples
./mattermost team archive team1

mattermost team create

Description
Create a team.
Format
mattermost team create
Examples
./mattermost team create --name mynewteam --display_name "My New Team"
./mattermost teams create --name private --display_name "My New Private Team" --private
Options
--display_name string   Team Display Name
--email string          Administrator Email (anyone with this email is automatically a team admin)
--name string           Team Name
--private               Create a private team.

mattermost team delete

Description
Permanently delete a team along with all related information, including posts from the database. Before running this command, see the note about {team-name}.
Format
mattermost team delete {team-name}
Example
./mattermost team delete myteam
Options
--confirm   Confirm you really want to delete the team and a DB backup has been performed.

mattermost team list

Supported in Mattermost v4.10 and later

Description
List all teams on the server.
Format
mattermost team list
Example
./mattermost team list

mattermost team modify

Description
Modify a team’s public/private type.
Format
mattermost team modify [team] [flag]
Example
./mattermost team myteam --private
./mattermost team myteam --public

mattermost team remove

Description
Remove users from a team. Before running this command, see the note about {team-name}.
Format
mattermost team remove {team-name} {users}
Example
./mattermost team remove myteam user@example.com username

mattermost team rename

Description
Rename a team.
Format
mattermost team rename {team} newteamname --display_name "New Display Name"
Examples
./mattermost team rename myteam newteamname --display_name "New Display Name"
Options
--display_name string   Team Display Name

mattermost team restore

Description
Restore a previously archived team.
Format
mattermost team restore {team}
Example
./mattermost team restore myteam

mattermost user

Description
Commands to manage users.

Child Commands


mattermost user activate

Description
Activate users that have been deactivated. If activating multiple users, use a space-separated list.
Format
mattermost user activate {emails, usernames, userIds}
Examples
./mattermost user activate user@example.com
./mattermost user activate username1 username2

mattermost user convert

Description
Convert a user to a bot, or convert a bot to a user account.
Format
mattermost user convert {emails, usernames, userIds} --bot
OR
mattermost user convert {bot_id} --user --email {email_address} --password {new_password}
Examples
./mattermost user convert user@example.com --bot
./mattermost user convert username1 username2 --bot
./mattermost user convert old_bot --user --email real_user@example.com --password Password1
Options
--bot string       Convert user to bot.  Supports converting multiple bots at once, use a space-separated list.
--user string      Convert bot to user.  Supports converting 1 account per command. The converted user will have the role of `system_user` set.

mattermost user create

Description
Create a user.
Format
mattermost user create
Examples
./mattermost user create --email user@example.com --username userexample --password Password1
./mattermost user create --firstname Joe --system_admin --email joe@example.com --username joe --password Password1
Options
--email string       Email
--firstname string   First Name
--lastname string    Last Name
--locale string      Locale (ex: en, fr)
--nickname string    Nickname
--password string    Password
--system_admin       Make the user a system administrator
--username string    Username

mattermost user deactivate

Description
Deactivate a user. Deactivated users are immediately logged out of all sessions and are unable to log back in.
Format
mattermost user deactivate {emails, usernames, userIds}
Examples
./mattermost user deactivate user@example.com
./mattermost user deactivate username

mattermost user delete

Description

Permanently delete a user and all related information, including posts from the database.

Does not delete content from the file storage. You can manually delete all file uploads for a given user as uploads contain the CreatorId field. User avatars are stored in data/users/<userid>/profile.png.

Format
mattermost user delete {users}
Example
./mattermost user delete user@example.com
Options
--confirm   Confirm you really want to delete the user and a DB backup has been performed.

mattermost user deleteall

Description

Permanently delete all users and all related information, including posts.

Does not delete content from the file storage. You can manually delete all file uploads and avatars. All uploads contain the CreatorId field and user avatars are stored in data/users/<userid>/profile.png.

Format
mattermost user deleteall
Example
./mattermost user deleteall
Options
--confirm   Confirm you really want to delete the user and a DB backup has been performed.

mattermost user email

Description
Set a user’s email.
Format
mattermost user email {user} {new email}
Example
./mattermost user email user@example.com newuser@example.com

mattermost user invite

Description
Send a user an email invite to a team. You can invite a user to multiple teams by listing the team names or team IDs.
Format
mattermost user invite {email} {teams}
Examples
./mattermost user invite user@example.com myteam
./mattermost user invite user@example.com myteam1 myteam2

mattermost user migrate_auth

Description
Migrates all existing Mattermost user accounts from one authentication provider to another. For example, you can upgrade your authentication provider from email to AD/LDAP, or from AD/LDAP to SAML. Output will display any accounts that are not migrated successfully. These accounts might be blocked because of filters in your AD/LDAP configuration in the System Console.

Migrate to AD/LDAP

Parameters
  • from_auth: The authentication service from which to migrate user accounts. Supported options: email, gitlab, saml.
  • to_auth: The authentication service to which to migrate user accounts. Supported options: ldap.
  • match_field: The field that is guaranteed to be the same in both authentication services. For example, if the user emails are consistent set to email. Supported options: email, username.
Format
mattermost user migrate_auth {from_auth} ldap {match_field}
Example
./mattermost user migrate_auth email ldap email
Options
--force  Ignore duplicate entries on the AD/LDAP server.
--dryRun Run a simulation of the migration process without changing the database.

Migrate to SAML

Supported in Mattermost v4.8 and later

Parameters

  • from_auth: The authentication service from which to migrate user accounts. Supported options: email, gitlab. ldap.
  • to_auth: The authentication service to which to migrate user accounts. Supported options: saml.
  • users_file: The path of a JSON file with the usernames and emails of all users to migrate to SAML. The username and email must be the same as in your SAML service provider. Moreover, the email must match the email address of the Mattermost user account. An example of the users file is below:
{
  "user1@email.com": "user.one",
  "user2@email.com": "user.two"
}
Users file generation

Generating the users_file depends on how the system is configured and which SAML service provider is used. Below are two sample scripts for OneLogin and Okta service providers. For ADFS, you can use the AD/LDAP protocol to directly extract the users information and export it to a JSON file.

After generating the users_file, you can manually update the file to obtain a list of Mattermost user accounts you want to migrate to SAML. Note that users listed in users_file that do not yet exist in Mattermost are ignored during the migration process.

OneLogin:

from onelogin.api.client import OneLoginClient
import json

client_id = input("Client id: ")
client_secret = input("Secret: ")
region = input("Region (us, eu): ")

client = OneLoginClient(client_id, client_secret, region)

mapping = {}
for user in client.get_users():
    mapping[user.email] = user.username

with file("saml_users.json", "w") as fd:
    json.dump(mapping, fd)

Okta:

from okta import UsersClient
import json

base_url = input("Base url (example: https://example.okta.com): ")
api_token = input("API Token: ")

usersClient = UsersClient(base_url, api_token)

users = usersClient.get_paged_users(limit=25)

mapping = {}

for user in users.result:
    mapping[user.profile.email] = user.profile.login

while not users.is_last_page():
    users = usersClient.get_paged_users(url=users.next_url)
    for user in users.result:
        mapping[user.profile.email] = user.profile.login

with file("saml_users.json", "w") as fd:
    json.dump(mapping, fd)

ADFS:

import ldap
import json
import getpass

ldap_host = input('Ldap Host (example ldap://localhost:389): ')
base_dn = input('Base DN (example dc=mm,dc=test,dc=com): ')
bind_dn = input('Bind DN (example ORGANIZATION\username): ')
password = getpass.getpass('Password: ')
user_object_class = input('User object class (example organizationalPerson): ')
username_field = input('Username field (example sAMAccountName): ')
mail_field = input('Mail field (example mail): ')

l = ldap.initialize(ldap_host)
l.simple_bind_s(bind_dn, password)
page_control = ldap.controls.libldap.SimplePagedResultsControl(True, size=1000, cookie='')
r = l.search_ext(base_dn, ldap.SCOPE_SUBTREE, '(objectClass='+user_object_class+')', [username_field, mail_field],         serverctrls=[page_control])

mapping = {}
while True:
    rtype, rdata, rmsgid, serverctrls = l.result3(r)

    for dn, entry in rdata:
        if mail_field in entry and len(entry[mail_field]) >= 1 and username_field in entry and len(entry[username_field]) >= 1:
            mapping[entry[mail_field][0].decode('utf-8')] = entry[username_field][0].decode('utf-8')

    controls = [control for control in serverctrls if control.controlType == ldap.controls.libldap.SimplePagedResultsControl.controlType]
    if not controls:
        print('The server ignores RFC 2696 control')
        break
    if not controls[0].cookie:
        break
    page_control.cookie = controls[0].cookie
    r = l.search_ext(base_dn, ldap.SCOPE_SUBTREE, '(objectClass='+user_object_class+')', [username_field, mail_field], serverctrls=[page_control])

with open("saml_users.json", "w") as fd:
    json.dump(mapping, fd)
Format
mattermost user migrate_auth {from_auth} saml {users_file}
Example
./mattermost user migrate_auth email saml users.json
Options
--auto   Automatically migrate all users without a {users_file}. Assumes the usernames and emails are identical between Mattermost and SAML services.
--dryRun Run a simulation of the migration process without changing the database. Useful to test if the migration results in any errors. You can use this option with or without a {users_file}.

mattermost user password

Description
Set a user’s password.
Format
mattermost user password {user} {password}
Example
./mattermost user password user@example.com Password1

mattermost user resetmfa

Description
Turns off multi-factor authentication for a user. If MFA enforcement is enabled, the user will be forced to re-enable MFA with a new device as soon as they log in.
Format
mattermost user resetmfa {users}
Example
./mattermost user resetmfa user@example.com

mattermost user verify

Description
Verify the email address of a new user.
Format
mattermost user verify {users}
Example
./mattermost user verify user1

mattermost version

Description
Displays Mattermost version information.
Format
mattermost version

mattermost webhook

Description
Commands to manage webhooks.
Child Commands

mattermost webhook create-incoming

Description
Create an incoming webhook within specific channel.
Format
mattermost webhook create-incoming
Examples
./mattermost webhook create-incoming --channel [channelID] --user [userID] --display-name [display-name] --description [webhookDescription] --lock-to-channel --icon [iconURL]
Options
--channel string           Channel ID
--user string              User ID
--display-name string      Incoming webhook display name
--description string       Incoming webhook description
--lock-to-channel boolean  (True/False) Lock incoming webhook to channel
--icon [iconURL]           Icon URL

mattermost webhook create-outgoing

Description
Create an outgoing webhook which allows external posting of messages from a specific channel.
Format
mattermost webhook create-outgoing
Examples
./mattermost webhook create-outgoing --team myteam --channel mychannel --user myusername --display-name mywebhook --description "My cool webhook" --trigger-when start --trigger-word "build" --icon http://localhost:8000/my-slash-handler-bot-icon.png --url http://localhost:8000/my-webhook-handler --content-type "application/json"

./mattermost webhook create-outgoing --team myotherteam --channel mychannel --user myusername --display-name myotherwebhook --description "My cool webhook" --trigger-when exact --trigger-word "build" --trigger-word "test" --trigger-word "third-trigger" --icon http://localhost:8000/my-slash-handler-bot-icon.png --url http://localhost:8000/my-webhook-handler --url http://example.com --content-type "application/json"
Options
--team string [REQUIRED]                Team name or ID
--channel string                        Channel name or ID
--user string [REQUIRED]                User username, email, or ID
--display-name string [REQUIRED]        Outgoing webhook display name
--description string                    Outgoing webhook description
--trigger-words stringArray [REQUIRED]  Words to trigger webhook
--trigger-when string [REQUIRED]        When to trigger webhook (exact: for first word matches a trigger word exactly, start: for first word starts with a trigger word) (default "exact")
--icon [iconURL]                        Icon URL
--url stringArray [REQUIRED]            Callback URLs
--content-type string                   Content-type
--h, --help         Help for create-outgoing

mattermost webhook delete

Description
Delete incoming and outgoing webhooks. If deleting multiple webhooks, use a space-separated list.
Format
mattermost webhook delete [webhookID]
Examples
./mattermost webhook delete ggwpz8c1oj883euk98wfm9n1cr

mattermost webhook list

Description
List all webhooks.
Format
mattermost webhook list {team}
Examples
./mattermost webhook list team1
./mattermost webhook list
Options
--team string  Specific team results to return.  If not specified, all teams will be included.

mattermost webhook modify-incoming

Description
Modify an existing incoming webhook by changing its title, description, channel or icon url.
Format
mattermost webhook modify-incoming {webhookId}
Examples
./mattermost webhook modify-incoming [webhookID] --channel [channelID] --display-name [displayName] --description [webhookDescription] --lock-to-channel --icon [iconURL]
Options
--channel string              Channel ID
--display-name string         Incoming webhook display name
--description string          Incoming webhook description
--lock-to-channel boolean     (True/False) Lock incoming webhook to channel
--icon [iconURL]              Icon URL

mattermost webhook modify-outgoing

Description
Modify an existing outgoing webhook by changing its title, description, channel, trigger words, icon url, callback url, or content type.
Format
mattermost webhook modify-outgoing {webhookId}
Examples
./mattermost webhook modify-outgoing [webhookId] --channel [channelId] --display-name [displayName] --description "New webhook description" --icon http://localhost:8000/my-slash-handler-bot-icon.png --url http://localhost:8000/my-webhook-handler --content-type "application/json" --trigger-word test --trigger-when start`
Options
--channel string              Channel ID
--display-name string         Incoming webhook display name
--description string          Incoming webhook description
--trigger-word string array   Word(s) to trigger webhook
--trigger-when string         When to trigger webhook (exact: for first word matches a trigger word exactly, start: for first word starts with a trigger word)")
--icon [iconURL]              Icon URL
--url [callbackURL]           Callback URL
--content-type string         Content type

mattermost webhook show

Description
Show information about a webhook by providing the webhook ID. Returns display name, channel ID and team ID for both incoming and outgoing webhooks. Additionally returns callback URL, username, and icon URL for outgoing webhooks.
Format
mattermost webhook show [webhookId]
Examples
./mattermost webhook show [webhookId]

Mattermost 3.5 and earlier

Typing ./platform -help brings up documentation for the CLI tool. To return the help documentation in GitLab omnibus, type

sudo -u mattermost /opt/gitlab/embedded/bin/mattermost --config=/var/opt/gitlab/mattermost/config.json -help

Notes:

  • Parameters in CLI commands are order-specific.
  • If special characters (!, |, (, ), \, `, and ") are used, the entire argument needs to be surrounded by single quotes (e.g. -password 'mypassword!', or the individual characters need to be escaped out (e.g. -password mypassword\!).
  • Team name and channel name refer to the handles, not the display names. So in the url https://community.mattermost.com/core/channels/town-square team name would be core and channel name would be town-square

Tip

If you automate user creation through the CLI tool with SMTP enabled, emails will be sent to all new users created. If you run such a load script, it is best to disable SMTP or to use test accounts so that new account creation emails aren’t unintentionally sent to people at your organization who aren’t expecting them.

CLI Documentation:

Mattermost commands to help configure the system

NAME:
    platform -- platform configuration tool

USAGE:
    platform [options]

FLAGS:
    -config="config.json"             Path to the config file

    -username="someuser"              Username used in other commands

    -license="ex.mattermost-license"  Path to your license file

    -email="user@example.com"         Email address used in other commands

    -password="mypassword"            Password used in other commands

    -team_name="name"                 The team name used in other commands

    -channel_name="name"              The channel name used in other commands

    -channel_header="string"          The channel header used in other commands

    -channel_purpose="string"         The channel purpose used in other commands

    -channel_type="type"              The channel type used in other commands
                                      valid values are
                                        "O" - public channel
                                        "P" - private channel

    -role="system_admin"               The role used in other commands
                                       valid values are
                                         "" - The empty role is basic user
                                            permissions
                                         "system_admin" - Represents a system
                                            admin who has access to all teams
                                            and configuration settings.
COMMANDS:
    -create_team                      Creates a team.  It requires the -team_name
                                      and -email flag to create a team.
        Example:
            platform -create_team -team_name="name" -email="user@example.com"

    -create_user                      Creates a user.  It requires the -email and -password flag,
                                       and -team_name and -username are optional to create a user.
        Example:
            platform -create_user -team_name="name" -email="user@example.com" -password="mypassword" -username="user"

    -invite_user                      Invites a user to a team by email. It requires the -team_name
                                        and -email flags.
        Example:
            platform -invite_user -team_name="name" -email="user@example.com"

    -join_team                        Joins a user to the team.  It requires the -email and
                                       -team_name flags.  You may need to logout of your current session
                                       for the new team to be applied.
        Example:
            platform -join_team -email="user@example.com" -team_name="name"

    -assign_role                      Assigns role to a user.  It requires the -role and
                                      -email flag.  You may need to log out
                                      of your current sessions for the new role to be
                                      applied.
        Example:
            platform -assign_role -email="user@example.com" -role="system_admin"

    -create_channel                   Create a new channel in the specified team. It requires the -email,
                                      -team_name, -channel_name, -channel_type flags. Optional you can set
                                      the -channel_header and -channel_purpose.
        Example:
            platform -create_channel -email="user@example.com" -team_name="name" -channel_name="channel_name" -channel_type="O"

    -join_channel                     Joins a user to the channel.  It requires the -email, -channel_name and
                                      -team_name flags.  You may need to logout of your current session
                                      for the new channel to be applied.  Requires an enterprise license.
        Example:
            platform -join_channel -email="user@example.com" -team_name="name" -channel_name="channel_name"

    -leave_channel                     Removes a user from the channel.  It requires the -email, -channel_name and
                                       -team_name flags.  You may need to logout of your current session
                                       for the channel to be removed.  Requires an enterprise license.
        Example:
            platform -leave_channel -email="user@example.com" -team_name="name" -channel_name="channel_name"

    -list_channels                     Lists all channels for a given team.
                                       It will append ' (archived)' to the channel name if archived.  It requires the
                                       -team_name flag.  Requires an enterprise license.
        Example:
            platform -list_channels -team_name="name"

    -restore_channel                  Restores a previously deleted channel.
                                      It requires the -channel_name flag and
                                      -team_name flag.  Requires an enterprise license.
        Example:
            platform -restore_channel -team_name="name" -channel_name="channel_name"

    -reset_password                   Resets the password for a user.  It requires the
                                      -email and -password flag.
        Example:
            platform -reset_password -email="user@example.com" -password="newpassword"

    -reset_mfa                        Turns off multi-factor authentication for a user.  It requires the
                                      -email or -username flag.
        Example:
            platform -reset_mfa -username="someuser"

    -reset_database                   Completely erases the database causing the loss of all data. This
                                      will reset Mattermost to it's initial state. (note this will not
                                      erase your configuration.)

        Example:
            platform -reset_database

    -permanent_delete_user            Permanently deletes a user and all related information
                                      including posts from the database.  It requires the
                                      -email flag.  You may need to restart the
                                      server to invalidate the cache
        Example:
            platform -permanent_delete_user -email="user@example.com"

    -permanent_delete_all_users       Permanently deletes all users and all related information
                                      including posts from the database.  It requires the
                                      -team_name, and -email flag.  You may need to restart the
                                      server to invalidate the cache
        Example:
            platform -permanent_delete_all_users -team_name="name" -email="user@example.com"

    -permanent_delete_team            Permanently deletes a team along with
                                      all related information including posts from the database.
                                      It requires the -team_name flag.  You may need to restart
                                      the server to invalidate the cache.
        Example:
            platform -permanent_delete_team -team_name="name"

    -upload_license                   Uploads a license to the server. Requires the -license flag.

        Example:
            platform -upload_license -license="/path/to/license/example.mattermost-license"

    -migrate_accounts                 Migrates accounts from one authentication provider to another.
                                      Requires -from_auth -to_auth and -match_field flags. Supported
                                      options for -from_auth: email, gitlab, saml. Supported options
                                      for -to_auth: ldap. Supported options for -match_field: email,
                                      username. Output will display any accounts that are not migrated
                                      successfully.

        Example:
            platform -migrate_accounts -from_auth email -to_auth ldap -match_field username

    -upgrade_db_30                   Upgrades the database from a version 2.x schema to version 3 see
                                      http://www.mattermost.org/upgrading-to-mattermost-3-0/

        Example:
            platform -upgrade_db_30

    -version                          Display the current of the Mattermost platform

    -help                             Displays this help page