MapR 5.0 Documentation : maprcli and REST API Syntax


This guide provides information about the MapR command API. Most commands can be run on the command-line interface (CLI), or by making REST requests programmatically or in a browser. To run CLI commands, use an ssh connection to any node in the cluster. To use the REST interface, make HTTP requests to a node that is running the WebServer service. For information about the permissions required to run each API, see User Permission Requirements by API.

Each command reference page includes the command syntax, a table that describes the parameters, and examples of command usage. In each parameter table, required parameters are in bold text. For output commands, the reference pages include tables that describe the output fields. Values that do not apply to particular combinations are marked NA.


MapR REST calls use the following format:


Construct the <parameters> list from the required and optional parameters, in the format <parameter>=<value> separated by the ampersand (&) character. Example:

Values in REST API calls must be URL-encoded. For readability, the values in this document use the actual characters, rather than the URL-encoded versions.


To make REST calls using curl or wget, provide the username and password. To configure PAM for REST API, see PAM Configuration.

Curl Syntax

curl -k -u <username> https://<host>:<port>/rest/<command>...

To keep your password secure, do not provide it on the command line. Curl will prompt you for your password, and you can enter it securely.

Wget Syntax

wget --no-check-certificate --user <username> --ask-password https://<host>:<port>/rest/<command>...

To keep your password secure, do not provide it on the command line. Use the --ask-password option instead; then wget will prompt you for your password and you can enter it securely.

Command-Line Interface (CLI) Syntax

The MapR CLI commands are documented using the following conventions:

  • [Square brackets] indicate an optional parameter
  • <Angle brackets> indicate a value to enter

The following syntax example shows that the volume mount command requires the -name parameter, for which you must enter a list of volumes, and all other parameters are optional:

maprcli volume mount
    [ -cluster <cluster> ]
    -name <volume list>
    [ -path <path list> ]

For clarity, the syntax examples show each parameter on a separate line; in practical usage, the command and all parameters and options are typed on a single line. Example:

maprcli volume mount -name test-volume -path /test

Common Parameters

The following parameters are available for many commands in both the REST and command-line contexts.




The cluster on which to run the command. If this parameter is omitted, the command is run on the same cluster where it is issued. In multi-cluster contexts, you can use this parameter to specify a different cluster on which to run the command.


A ZooKeeper connect string, which specifies a list of the hosts running ZooKeeper, and the port to use on each, in the format: '<host>[:<port>][,<host>[:<port>]...]' Default: 'localhost:5181' In most cases the ZooKeeper connect string can be omitted, but it is useful in certain cases when the CLDB is not running.

Common Options

The following options are available for most commands in the command-line context.




When displaying tabular output from a command, omits the header row.


Shows the entire value. This is useful when the command response contains complex information. When -long is omitted, complex information is displayed as an ellipsis (...).


Displays command output in JSON format. When -json is omitted, the command output is displayed in tabular format.


Specifies a log level for API output. Legal values for this option are:

  • INFO
  • WARN


Some MapR CLI commands use filters, which let you specify large numbers of nodes or volumes by matching specified values in specified fields rather than by typing each name explicitly.

Filters use the following format:

[<field><operator>"<value>"]<and>[<field><operator>"<value>"] ...


Field on which to filter.  The field depends on the command with which the filter is used.


An operator for that field:

  • == - Exact match
  • != - Does not match
  • > - Greater than
  • <  - Less than
  • >= - Greater than or equal to
  • <=  - Less than or equal to


Value on which to filter. Wildcards (using *) are allowed for operators == and !=. There is a special value all that matches all values.

You can use the wildcard (*) for partial matches. For example, you can display all volumes whose owner is root and whose name begins with test as follows:

maprcli volume list -filter [n=="test*"]and[on=="root"]

maprcli commands and REST APIs do not support OR conditions.


The commands return responses in JSON or in a tabular format. When you run commands from the command line, the response is returned in tabular format unless you specify JSON using the -json option; when you run commands through the REST interface, the response is returned in JSON.


On a successful call, each command returns the error code zero (OK) and any data requested. When JSON output is specified, the data is returned as an array of records along with the status code and the total number of records. In the tabular format, the data is returned as a sequence of rows, each of which contains the fields in the record separated by tabs.


	"total":<number of records>,




<heading>   <heading>   <heading> ...
<field>     <field>     <field> ...


When an error occurs, the command returns the error code and descriptive message.


            "id":<error code>,
            "desc":"<command>: <error message>"


 ERROR (<error code>) -  <command>: <error message>