Countly Command Line


Both the Countly Lite and Countly Enterprise come with the command countly where you can perform specific actions, including backup and restore.

When Countly is installed, the command countly is also installed on your Linux server. Basic usage is as follows (as root):

# countly command optional-parameters

Basic Commands

These are the basic commands you can do with countly command:

  • countly start: Starts Countly process
  • countly stop: Stops Countly process
  • countly restart: Restarts Countly
  • countly status: Outputs process status, output depends on init system type
  • countly upgrade: Starts upgrade process
  • countly usage: Prints out usage information
  • countly version: Gives Countly version
  • countly test: Runs countly test set
  • countly dir: Outputs absolute path to directory where Countly is installed

Above, most of the commands are self-explanatory. Below you can find detailed explanations of commands.

Upgrading Countly

Countly can be upgraded via command line easily. These are the basic steps for upgrading:

  1. First, you should extract new Countly package on top of your existing installation (hint: use countly dir command to know where Countly is installed)
  2. Run countly upgrade

countly upgrade command does the following:

  1. It runs npm to install any new dependencies; in your case there won't be any new dependencies.
  2. It executes grunt dist-all to minify all files and make production files from them for more effective loading.
  3. It restarts Countly's Nodejs process to take into account new files changes.

After countly upgrade, go to your dashboard and start working with your new, shiny Countly platform.

Backing up and Restoring Countly

To make automatic backups to your server, you can run countly backup on the command line, or provide a cron job that runs every day or week. This cron job ideally backs up Countly data to a directory of your choice.

The following command backs up database, Countly configuration, and user files (e.g., app images, user images, certificates, etc).

All Database Files
countly backup /var/backups/countly

Additionally you can back up files or database separately by calling countly backupdb or countly backupfiles.

Note: Countly backup command simply copies files and exports database. You would need to ensure back up rotation and archiving yourself, depending on your needs.

You can restore Countly from backup by running restore command and pointing it to the same path you provided for backup. Similarly, you can restore only files by calling countly restorefiles and only db by calling countly restoredb

All Database Files
countly restore /var/backups/countly

Note: if you want to restore Countly on clean server, you need to install Countly itself and then run restore command.

Updating Countly Components

countly update command has the ability to update some components of Countly server. Currently this command supports following parameters:

  • countly update translations: Retrieves latest translated localization files from Countly's transifex project
  • countly update devices: Retrieves latest list of device ids to prettier device names
  • countly update geoip: Retrieves latest geoip-lite IP to city mapping files (can consume lots of RAM during upgrade)
  • countly update sdk-web: Retrieves latest version of web SDK to be hosted with your Countly installation in
countly update sdk-web

Getting More Information About Plugins

countly plugin command can enable or disable a plugin, as well as check current status and version of the plugin.

This command supports following parameters:

  • countly plugin list: List all available plugins
  • countly plugin list states: List all available plugins with their states
  • countly plugin enable <pluginname>: Enables plugin if plugin was not yet enabled
  • countly plugin upgrade <pluginname>: Run plugin installation script only (even if plugin is already enabled)
  • countly plugin disable <pluginname>: Disables plugin if plugin was enabled
  • countly plugin status <pluginname>: Outputs status of the plugin: enabled or disabled
  • countly plugin version <pluginname>: Outputs version of the plugin

Note: after enabling or disabling one or multiple plugins, you need to complete the process by running countly upgrade to prepare needed production files and restart countly process

countly plugin enable crashes

# In order for changes to take affect
countly upgrade

Managing Countly Configuration

countly config command allows you to manage Countly configurations from command line, like checking value of specific configs or changing their values.

This command supports following parameters:

  • countly config list: List all configuration options
  • countly config list values: List all configuration options and their current values
  • countly config <>: Show specific configuration value
  • countly config <> <value>: Change specific configuration value
  • countly config <> null: Removes specific configuration
countly config frontend.production false

MongoDB Connection

countly mongo command outputs connection parameters for MongoDB. By connection parameter, for example, when you connect to a MongoDB, you need to type mongo --host If it has authentication, you also need to pass username and password. If it is a replica set or connection is via SSL, things are a bit complex.

This command makes it easy to output those connection parameters to connect to the MongoDB database. It parses config.js and generates those arguments.

For example, running countly mongo on a Countly instance having a remote MongoDB database with authentication will output the following:

countly mongo
--host --username test --password test123 --authenticationDatabase admin

Since output includes parameters required to connect to this remote database, giving this command:

mongotop $(countly mongo)

will execute the following:

mongotop --host --username test --password test123 --authenticationDatabase admin

This way, it is a lot more convenient to work with MongoDB commands, such as:

mongotop $(countly mongo)
mongoexport $(countly mongo countly_drill)
mongo countly $(countly mongo)

Making API Requests

There is a simple countly api command to make an HTTP request to the same Countly server with provided path and parameters. Additionally, you can use countly api pretty to format JSON response from the api request.

For more information about possible api requests, you can read REST API reference section.

simple pretty
countly api "/o/analytics/dashboard?api_key=API_KEY&app_id=APP_ID"

countly api pretty "/o/analytics/dashboard?api_key=API_KEY&app_id=APP_ID"


I have the latest data backup, if I restore the data, will it be merged to the existing backup or replaced?

The restored data will be merged with the existing data, i.e., all documents will be merged into the existing collection of the restored database. However we strongly recommend not to use the --drop flag, as it replaces the data. As the database is MongoDB, the restore operation that is used is mongorestore. 


Looking for help?