.. meta:: :description: This documentation will guide you through the use of the Memset API. .. index:: single: shell Memset API Shell ================ The *Memset API interactive shell* (**ma-shell** for short) is a full featured XMLRPC client that enables remote command invocation from a text terminal. It can run a single command or an interactive session, supports JSON and XML output as well as output redirection into a file. ma-shell Invocation ------------------- **ma-shell** can be invoked with the **-h** flag to get an online help screen:: Usage: ma-shell [options] [command [param_name param_value ...]] Memset API interactive shell Options: --version show program's version number and exit -h, --help show this help message and exit -u URL, --url=URL API URL (default: https://%s:@api.memset.com/v1/xmlrpc) -k KEY, --api-key=KEY API KEY (required) -x, --xml Use XML as output format (default: JSON) The only required parameter is **-k KEY** to provide a valid API key. In all the following examples API_KEY_HEX is used instead of a real API key. If no command is provided, **ma-shell** will enter the interactive mode advertising the version number and displaying a command prompt that shows the tail of the used key:: (Memset API shell v0.2) [...a32a1fe9]> The interactive session can be closed with the **quit** command or with **^D** (end of file). If a command is provided, **ma-shell** executes it and writes the result to standard output before exiting:: $ ./ma-shell.py -k API_KEY_HEX help system.listMethods List all the public methods The output can be redirected to a file using standard shell redirection. The method invocation will use JSON by default as the output format for structured responses. XML output can be obtained using **-x** flag:: ./ma-shell.py -k API_KEY_HEX -x service.info name myserver1 LIVE GBP miniserver myserver1 20110917T00:00:00 21.60 www 20110617T00:00:00 4.34 Note that when an interactive session has been started, the output format can't be changed. Command Invocation ------------------ There are two local commands: * **quit**: exit the interactive session. * **help [command]**: used to describe commands. The **help** command without argument will display a general help screen. Use **help remote** to get the list of remote commands. The remote command list is retrieved from the API service at session start. When **help** is used with a remote command, the information is obtained directly from the API service. Remote Command Invocation ^^^^^^^^^^^^^^^^^^^^^^^^^ Remote commands without parameters can be executed as-is using the command name, for example:: [...a32a1fe9]> service.list (service.list result) [ { "status": "LIVE", "renewal_price_currency": "GBP", "type": "cloudstorage", "name": "mystorage1", "expiry_date": "20111112T00:00:00", "renewal_price_amount": 24.0, "nickname": "", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.0 }, { "status": "LIVE", "renewal_price_currency": "GBP", "type": "miniserver", "name": "myserver1", "expiry_date": "20110917T00:00:00", "renewal_price_amount": 21.60, "nickname": "www", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.34 } ] In the case of remote commands that require parameters, the parameters must be provided in name/value pairs. The number and name of the parameters depends on the remote command and is specified on its documentation. For example, :func:`service.info` requires a single parameter named **name**. Its invocation is as follows:: ./ma-shell.py -k API_KEY_HEX service.info name myserver1 { "status": "LIVE", "renewal_price_currency": "GBP", "type": "miniserver", "name": "myserver1", "expiry_date": "20110917T00:00:00", "renewal_price_amount": 21.60, "nickname": "www", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.34 } With commands that require more than one parameter, the order is not important as long as the name/value pairs are correct. For example, :func:`service.set_nickname` requires two different parameters:: [...a32a1fe9]> service.set_nickname name myserver1 nickname webserver (service.set_nickname result) { "nickname": "webserver" } The result would be the same if the **nickname** parameter were first. By default all parameter values are treated as strings, and a **(type)** prefix can be used to indicate the type of a specific value. The following types are supported: * **(string)**: a string value (default). * **(int)**: an integer value. * **(float)**: a decimal number value. * **(boolean)**: a boolean value (True or False, 1 or 0). * **(list)**: a comma separated list of strings. For example, using a list in the **type** parameter of :func:`service.list`:: [...a32a1fe9]> service.list type (list) cloudstorage,miniserver (service.list result) [ { "status": "LIVE", "renewal_price_currency": "GBP", "type": "miniserver", "name": "myserver1", "expiry_date": "20110917T00:00:00", "renewal_price_amount": 21.60, "nickname": "www", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.34 }, { "status": "LIVE", "renewal_price_currency": "GBP", "type": "cloudstorage", "name": "mystorage1", "expiry_date": "20111112T00:00:00", "renewal_price_amount": 24.0, "nickname": "", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.0 } ] The output of any specific remote command invocation can be stored in a file using the pipe (**¦**) operator followed by the desired file name:: [...a32a1fe9]> service.list | out.json (service.list result) [ { "status": "LIVE", "renewal_price_currency": "GBP", "type": "cloudstorage", "name": "mystorage1", "expiry_date": "20111112T00:00:00", "renewal_price_amount": 24.0, "nickname": "", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.0 }, { "status": "LIVE", "renewal_price_currency": "GBP", "type": "miniserver", "name": "myserver1", "expiry_date": "20110917T00:00:00", "renewal_price_amount": 21.60, "nickname": "www", "start_date": "20110617T00:00:00", "renewal_price_vat": 4.34 } ] (result piped to out.json) The pipe is not needed when running one single command, and the shell redirection can be used:: ./ma-shell.py -k API_KEY_HEX service.list > out.json Code and License ---------------- **ma-shell** is open source in terms of **MIT** license and can be obtained for free: https://github.com/memset/ma-shell.