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:

Support for multiple instances.
Advanced cooperation with the Logger module.
Support for static and dynamic commands.
Smart command completion with the Tab key.
Built-in: clear, colors, history, and resize commands.
Viewing recently executed commands using the Up/Down keys.
Text edition using Left/Right/End/Home/Insert keys.
Support for ANSI escape codes for cursor control and color printing (VT100).
Support for multiline commands.
Built-in handler to display help for the commands.

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

Bluetooth
USB CDC ACM
UART
RTT

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

Usage

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_CREATE_STATIC_SUBCMD_SET(m_sub_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),
 NRF_CLI_SUBCMD_SET_END
};
/* Creating subcommands (level 1 command) array for command "counter".
 Subcommands must be added in alphabetical order */
NRF_CLI_CREATE_STATIC_SUBCMD_SET(m_sub_counter)
{
 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),
 NRF_CLI_SUBCMD_SET_END
};
/* Creating root (level 0) command "counter" */
NRF_CLI_CMD_REGISTER(counter, &m_sub_counter, "display counter on terminal screen", cmd_counter);
NRF_CLI_RTT_DEF(m_cli_rtt_transport);
NRF_CLI_DEF(m_cli_rtt, "rtt_cli:~$ ", &m_cli_rtt_transport.transport, '\n', 4);
int main(void)
{
 ret_code_t ret;
 APP_ERROR_CHECK(NRF_LOG_INIT(NULL));
 /* CLI configured as NRF_LOG backend */
 ret = nrf_cli_init(&m_cli_rtt, NULL, true, true, NRF_LOG_SEVERITY_INFO);
 APP_ERROR_CHECK(ret);
 ret_code_t ret = nrf_cli_start(&m_cli_rtt);
 APP_ERROR_CHECK(ret);
 /* Below text will be printed on the CLI */
 NRF_LOG_RAW_INFO("Hello word.\r\n");
 while (true)
 {
 nrf_cli_process(&m_cli_rtt);
 }
}

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

Note: 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:

clear, colors, history, and resize are built-in commands which have been registered by nrf_cli.c,
counter has been registered in example code above by main.c,
log has been registered by nrf_log_frontend.c.

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

Commands

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

Root command (level 0): Kept in the section variable area.
Static subcommand (level > 0): Number and syntax must be known during compile time. Kept in the software module.
Dynamic subcommand (level > 0): Number and syntax does not need to be known during compile time. Created in the software module.

Creating commands

Use the following macros for adding CLI commands:

NRF_CLI_CMD_REGISTER - Create root command. Each and every root command shall have unique syntax.
NRF_CLI_CMD - Initialize a command.
NRF_CLI_CREATE_STATIC_SUBCMD_SET - Create a static subcommands array.
Static subcommands must be added in alphabetical order to ensure correct smart completion.
NRF_CLI_SUBCMD_SET_END - shall be placed as last in NRF_CLI_CREATE_STATIC_SUBCMD_SET macro.
NRF_CLI_CREATE_DYNAMIC_CMD - Create a dynamic subcommands array.
Dynamic subcommands must be returned in alphabetical order to ensure correct smart completion.

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

clear - Clears the screen.
colors - Toggles colored syntax. This might be useful in case of Bluetooth CLI to limit the amount of transferred bytes.
history - Shows the recently entered commands. By default, the CLI has 8 memory blocks of 32 bytes each reserved for history. A command longer than 32 bytes will take more than one block, and history will contain less than 8 commands.
resize - Must be executed when terminal width is different than 80 chars or after each change of terminal width. It ensures proper multiline text display and Left/Right/End/Home buttons handling. It can be also called with a parameter (subcommand): resize default. When run, the CLI will send terminal width = 80 to the terminal and assume successful delivery.

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);
 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[] = {
 NRF_CLI_OPT(
 "--test",
 "-t",
 "dummy option help string"
 )
 };
 if ((argc == 1) || nrf_cli_help_requested(p_cli))
 {
 nrf_cli_help_print(p_cli, opt, ARRAY_SIZE(opt));
 return;
 }
 if (argc != 2)
 {
 nrf_cli_fprintf(p_cli, NRF_CLI_ERROR, "%s:%s", argv[0], " bad parameter count\r\n");
 return;
 }
 if (!strcmp(argv[1], "-t") || !strcmp(argv[1], "--test"))
 {
 nrf_cli_fprintf(p_cli, NRF_CLI_NORMAL, "Dummy test option.\r\n");
 return;
 }
 /* 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.

Warning: 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.