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"
    

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:: none

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.