Command line tools#

plans-img Available on all plans

deployment-img self-hosted deployments

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

Important

From Mattermost v6.0, the majority of these CLI commands have been replaced with equivalents available using the mmctl command line tool. However, mattermost import commands, mattermost export commands, and related subcommands, remain available and fully supported from Mattermost v6.0.

These mattermost commands include the following functionality:

Compliance Export

  • Export data

  • Schedule an export job

Database

  • Initialize the database, execute migrations, and load custom defaults

  • Migrate the database schema for unapplied migrations

  • Reset the database to its initial state

  • Return the most recently applied version number

  • Roll back database migrations

Server Operations

  • Start the Mattermost job server

  • Run the Mattermost server

  • Display Mattermost version information

Use the CLI#

To run the CLI commands, you must be in the Mattermost root directory. On a default installation of Mattermost, the root directory is /opt/mattermost. If you followed our standard installation process, you must run the commands as the user mattermost. The name of the executable is mattermost, and it can be found in the /opt/mattermost/bin directory.

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

cd /opt/mattermost/
sudo -u mattermost bin/mattermost version

Note

  • Ensure you run the Mattermost binary as the mattermost user. Running it as root user (for example) may cause complications with permissions as the binary initiates plugins and accesses various files when running CLI commands. Running the server as root may result in ownership of the plugins and files to be overwritten as well as other potential permissions errors.

  • When running CLI commands on a Mattermost installation that has the configuration stored in the database, you might need to pass the database connection string as:

    bin/mattermost --config="postgres://mmuser:mostest@localhost:5432/mattermost_test?sslmode=disable\u0026connect_timeout=10"

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 /opt/gitlab/embedded/bin/chpst -e /opt/gitlab/etc/mattermost/env -P -U mattermost:mattermost -u mattermost:mattermost /opt/gitlab/embedded/bin/mattermost version

Note

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

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

The Docker Install tab details and command references below also apply to the Mattermost docker preview image.

Note

  • The CLI is run in a single node which bypasses the mechanisms that a High Availability environment uses to perform actions across all nodes in the cluster. As a result, when running CLI commands in a High Availability environment, tasks that change configuration settings require a server restart.

  • Parameters in CLI commands are order-specific.

  • If special characters (!, |, (, ), \, ', or ") are used, the entire argument needs to be surrounded by single quotes, or the individual characters need to be escaped out.

mattermost CLI commands#

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 db#

Description

Commands related to the database

Child Commands
Options
-h, --help   help for db
-c, --config string   Configuration file to use

mattermost db downgrade#

Description

Rolls back database migrations. Requires either an update plan to roll back to, or comma-separated version numbers to be rolled back.

Format
mattermost db downgrade
Example
mattermost db downgrade 99,100,101
Options
--<plan-file> string      Runs the rollback migrations defined in the plan file.

mattermost db init#

Description

Initializes the database for a given data source name (DSN), executes migrations, and loads custom defaults when specified.

Format
mattermost db init
Examples

Use the config flag to pass the DSN:

mattermost db init --config postgres://localhost/mattermost

Run this command to use the MM_CONFIG environment variable:

MM_CONFIG=postgres://localhost/mattermost mattermost db init

Run this command to set a custom defaults file to be loaded into the database:

MM_CUSTOM_DEFAULTS_PATH=custom.json MM_CONFIG=postgres://localhost/mattermost mattermost db init

mattermost db migrate#

Description

Migrates the database schema if there are any unapplied migrations.

Child Commands
Format
mattermost db migrate
Example
mattermost db migrate
Options
--auto-recover bool     If the migration plan receives an error during migrations, this command will try to rollback migrations already applied within the plan. Not recommended without reviewing migration plan by combining --save-plan and --dry-run options.
--save-plan bool        Saves the plan for the migration into the file store so that it can be used for reviewing the plan or for downgrading.
--dry-run bool          Does not apply the migrations, but it validates how the migration would run based on the given conditions.

mattermost db reset#

Description

Resets the database to its initial state. Doesn’t start the application server. Only starts the store layer and truncates the tables, excluding the migrations table.

Format
mattermost db reset
Example
bin/mattermost db reset

mattermost db version#

Description

Returns the most recently applied version number.

Format
mattermost db version
Example
bin/mattermost export actiance --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (milliseconds since epoch, UTC) to export data from.
--batchSize int         The number of posts to export. The default of -1 means no limit.

mattermost export#

Note

plans-img-yellow Available only on Enterprise plans

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
bin/mattermost export actiance --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (milliseconds since epoch, UTC) to export data from.
--batchSize int         The number of posts to export. The default of -1 means no limit.

mattermost export bulk#

From Mattermost v6.0, this command has been deprecated in favor of mmctl export commands as the supported way to export data out of Mattermost.

mattermost export csv#

Description

Export data from Mattermost in CSV format.

Format
mattermost export csv
Example
bin/mattermost export csv --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (seconds since epoch, UTC) to export data from.
--batchSize int         The number of posts to export. The default of -1 means no limit.

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
bin/mattermost export global-relay-zip --exportFrom=1513102632
Options
--exportFrom string     Unix timestamp (seconds since epoch, UTC) to export data from.
--batchSize int         The number of posts to export. The default of -1 means no limit.

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
bin/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 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#

From Mattermost v6.0, this command has been deprecated in favor of mmctl import commands as the supported way to import data into Mattermost.

mattermost import slack#

See the mmctl import commands documentation as the preferred way to import Slack data into Mattermost.

Description

Import a team from a Slack export zip file.

Format

. code-block:: sh

mattermost import slack {team} {file}

Example
bin/mattermost import slack myteam slack_export.zip

mattermost jobserver#

Description

Start the Mattermost job server.

Format
mattermost jobserver
Example
bin/mattermost jobserver

mattermost server#

Description

Runs the Mattermost server.

Format
mattermost server

mattermost version#

Note

From Mattermost v6.5, this CLI command no longer interacts with the database. The mattermost db migrate CLI command has been introduced to trigger schema migrations.

Desription

Displays Mattermost version information.

Format
mattermost version

Troubleshooting#

Executing a command hangs and doesn’t complete#

If you have Bleve search indexing enabled, temporarily disable it in System Console > Experimental > Bleve and run the command again. You can also optionally use the new mmctl Command Line Tool.

Bleve does not support multiple processes opening and manipulating the same index. Therefore, if the Mattermost server is running, an attempt to run the CLI will lock when trying to open the indeces.

If you aren’t using the Bleve search indexing, feel free to post in our Troubleshooting forum to get help.