nRF5 SDK v17.1.0
Command Line Interface library

This module allows to create and handle a command line interface (CLI) with a user-defined command set. You can use it in examples where more than button/LED user interaction is required. This module can be considered a Unix-like command line interface with these features:

The module can be connected to any transport. At this point, the following transport layers are implemented:

For API documentation of this library, refer to Command Line Interface.


Use the NRF_CLI_DEF macro to create an instance of the CLI.

In the previous SDK releases, it was necessary to pass a correct newline character to this macro. Otherwise, the CLI did not respond correctly to the Enter button.
Beginning from nRF5 SDK v15.3.0, this parameter is redundant and is planned to be removed in the next major SDK release.
Settings for PuTTY
Newline character

The following code shows a simple use case of this library:

/* Creating subcommands (level 2 command) array for command "counter start". */
NRF_CLI_CMD(with_delay_ms, NULL, "help string", cmd_counter_start_delay_ms),
NRF_CLI_CMD(with_delay_s, NULL, "help string", cmd_counter_start_delay_s),
NRF_CLI_CMD(with_delay_us, NULL, "help string", cmd_counter_start_delay_us),
/* Creating subcommands (level 1 command) array for command "counter" using a macro working
with both C and C++ compilers.
NRF_CLI_CMD(reset, NULL, "help string", cmd_counter_reset),
NRF_CLI_CMD(start, &m_sub_counter_start, "help string", cmd_counter_start),
NRF_CLI_CMD(stop, NULL, "help string", cmd_counter_stop),
/* Creating root (level 0) command "counter" */
NRF_CLI_CMD_REGISTER(counter, &m_sub_counter, "display counter on terminal screen", cmd_counter);
NRF_CLI_DEF(m_cli_rtt, "rtt_cli:~$ ", &m_cli_rtt_transport.transport, '\n', 4);
int main(void)
/* CLI configured as NRF_LOG backend */
ret = nrf_cli_init(&m_cli_rtt, NULL, true, true, NRF_LOG_SEVERITY_INFO);
ret_code_t ret = nrf_cli_start(&m_cli_rtt);
/* Below text will be printed on the CLI */
NRF_LOG_RAW_INFO("Hello word.\r\n");
while (true)

Users may use the Tab key to complete a command/subcommand or to see the available subcommands for the currently entered command level. For example, when the cursor is positioned at the beginning of the command line and the Tab key is pressed, the user will see all root (level 0) commands:

clear cli counter history log resize
To view the subcommands that are available for a specific command, you must first type a space after this command and then hit Tab.

These commands are registered by various modules:

Then, if a user types a counter command and presses the Tab key, the console will only print the subcommands registered for this command:

reset start stop
When using the CLI module along with the Logger module, make sure that another backend using the same physical transport is disabled (e.g. NRF_LOG_BACKEND_UART_ENABLED if CLI over UART is used), or not initialized Raw backends are enabled in NRF_LOG_DEFAULT_BACKENDS_INIT.


CLI commands are organized in a tree structure and grouped into the following types:

Creating commands

Use the following macros for adding CLI commands:


Commands execution

Each command or subcommand on each level can either have or not have a handler. The CLI executes the handler that is found deepest in the command tree and further subcommands (without a handler) are passed as arguments. Characters within parentheses are treated as one argument. Each command or subcommand without a handler can be treated as an argument, or it can still have a subcommand with a handler and there is no problem for the user to execute it.

Built-in commands

Commands help

Every user-defined command, subcommand, or option can have its own help description. The help for commands and subcommands can be created with respective macros: NRF_CLI_CMD_REGISTER, NRF_CLI_CMD. In addition, you can define options for commands or subcommands using the macro NRF_CLI_OPT. By default, each and every command or subcommand has these two options implemented: "-h" and "--help".

In order to add help functionality to a command or subcommand, you must implement the help handler nrf_cli_help_print inside of a function.

The following code is an example of how commands can be processed:

static void cmd_counter(nrf_cli_t const * p_cli, size_t argc, char **argv)
ASSERT(p_cli->p_ctx && p_cli->p_iface && p_cli->p_name);
/* Extra defined dummy option */
static nrf_cli_getopt_option_t const opt[] = {
"dummy option help string"
nrf_cli_fprintf(p_cli, NRF_CLI_INFO, "Entering counter command\n");
/* Printing help if needed */
if ((argc == 1) || nrf_cli_help_requested(p_cli))
nrf_cli_help_print(p_cli, opt, ARRAY_SIZE(opt));
/* Expected command length for this handler, for example: counter -t or counter --test */
if (argc != 2)
nrf_cli_error(p_cli, "%s: bad parameter count", argv[0]);
/* Options must be handled with strcmp function */
if (!strcmp(argv[1], "-t") || !strcmp(argv[1], "--test"))
nrf_cli_print(p_cli, "Dummy test option.");
/* subcommands have their own handlers and they are not processed here */
nrf_cli_error(p_cli, "%s: unknown parameter: %s", argv[0], argv[1]);

It is recommended to use subcommands. Options apply mainly in the case when an argument with '-' or "--" is requested. The main benefit of using subcommands is that they can be prompted or completed with the Tab key. In addition, subcommands can have their own handler, which limits the usage of "if - else if" statements combination with the strcmp function.

Print functions

All of the following functions implemented by CLI API can be safely used only within a command context:

Do not use these functions outside of the command handler because this might lead to incorrect text display on the console. If any text should be displayed outside of the command context, then use the Logger module.


The CLI module can handle wildcards. This option can be activated in the sdk_config.h file by setting option NRF_CLI_WILDCARD_ENABLED.

Wildcards are interpreted correctly if they are used in commands without handlers. What is more, when commands are run with wildcards, going deeper in the command tree is not possible.

For example, if you want to set logging level to 'error' for the app module and all queue and balloc instances, you can execute the following command:

log enable error queue* balloc* app
Wildcard example
It is important to ensure that the command buffer is large enough to store all expanded commands.

Meta keys

The CLI module supports the following meta keys:

Implemented meta keys
Meta key
ctrl + a Moves the cursor to the beginning of the line.
ctrl + c Preserves the last command on the screen and starts a new command in a new line.
ctrl + e Moves the cursor to the end of the line.
ctrl + l Clears the screen and leaves the currently typed command at the top of the screen.
ctrl + u Clears the currently typed command.
ctrl + w Removes the word or part of the word to the left of the cursor.
Words separated by period instead of space are treated as one word.

Terminal settings

A strongly recommended terminal to use with the CLI module is PuTTY. It can be easily configured to send escape codes interpreted by the console. If other terminal is used, configure it according to the following PuTTY settings. See the below figures.

Mandatory PuTTY settings
Window size settings

If window width is set to a value different than 80, the user must execute the resize command to ensure correct text display.

UART and USB settings

Apply these settings when using UART or USB as the transport layer for the CLI module.

Serial settings
Terminal settings

RTT settings

Apply these settings when using RTT as the transport layer for the CLI module.

Connection settings
Terminal settings
Do not use J-Link Viewer to start an RTT session because PuTTY will not display characters correctly.

When debugging under Segger Embedded Studio with RTT configured as CLI transport, some characters might be directed to Segger Debug Window, instead of to PuTTY. To solve this problem, you need to deactivate RTT in SES:
Project settings->Debug->Debugger->RTT Enable-> Set to No.

Do not use the SES debug window to operate the console, because it significantly limits CLI capability. Use PuTTY or a similar terminal instead.

Usage examples

For usage examples of this library, see: Experimental: ATT_MTU Throughput Example, Experimental: Console over Bluetooth Application, Command Line Interface (CLI) Example, Capacitive Sensor Low-level Example, Flash Write Example, and TWIS Slave and TWI Master Mode Drivers Example.

Documentation feedback | Developer Zone | Subscribe | Updated