nRF5 SDK v14.0.0
Experimental: 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. The following code shows a simple use case of this library:

/* Creating subcommands (level 2 command) array for command "counter start".
Subcommands must be added in alphabetical order */
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".
Subcommands must be added in alphabetical order */
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 colors 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


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. Chars 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 const nrf_cli_getopt_option_t opt[] = {
"dummy option help string"
if ((argc == 1) || nrf_cli_help_requested(p_cli))
nrf_cli_help_print(p_cli, opt, ARRAY_SIZE(opt));
if (argc != 2)
nrf_cli_fprintf(p_cli, NRF_CLI_ERROR, "%s:%s", argv[0], " bad parameter count\r\n");
if (!strcmp(argv[1], "-t") || !strcmp(argv[1], "--test"))
nrf_cli_fprintf(p_cli, NRF_CLI_NORMAL, "Dummy test option.\r\n");
/* subcommands have their own handlers and they are not processed here */
nrf_cli_fprintf(p_cli, NRF_CLI_ERROR, "%s: unknown parameter: %s\r\n", 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.

Do not use function nrf_cli_fprintf 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.

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!

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