1.. zephyr:code-sample:: shell-module
2   :name: Custom Shell module
3   :relevant-api: shell_api
4
5   Register shell commands using the Shell API
6
7Overview
8********
9
10This is a simple application demonstrating how to write and register commands
11using the :ref:`Shell API <shell_api>`:
12
13Register Static commands
14   ``version`` is a static command that prints the kernel version.
15
16Conditionally Register commands
17   ``login`` and ``logout`` are conditionally registered commands depending
18   on :kconfig:option:`CONFIG_SHELL_START_OBSCURED`.
19
20Register Dynamic commands
21   See ``dynamic`` command and :zephyr_file:`samples/subsys/shell/shell_module/src/dynamic_cmd.c`
22   for details on how dynamic commands are implemented.
23
24Register Dictionary commands
25   ``dictionary`` implements subsect of dictionary commands.
26
27Set a Bypass callback
28   ``bypass`` implements the bypass callback.
29
30Set a Login command
31   ``login`` and ``logout`` implement the login and logout mechanism, respectively.
32
33Obscure user-input with asterisks
34   ``login`` and ``logout`` implement the feature of enabling and disabling
35   this functionality, respectively.
36
37Requirements
38************
39
40* A target configured with the shell interface, exposed through any of
41  its :ref:`backends <backends>`.
42
43Building and Running
44********************
45
46The sample can be built for several platforms.
47
48Emulation Targets
49=================
50
51The sample may run on emulation targets. The following commands build the
52application for the qemu_x86.
53
54.. zephyr-app-commands::
55   :zephyr-app: samples/subsys/shell/shell_module
56   :host-os: unix
57   :board: qemu_x86
58   :goals: run
59   :compact:
60
61After running the application, the console displays the shell interface, and
62shows the shell prompt, at which point the user may start the interaction.
63
64On-Hardware
65===========
66
67.. zephyr-app-commands::
68   :zephyr-app: samples/subsys/shell/shell_module
69   :host-os: unix
70   :board: nrf52840dk/nrf52840
71   :goals: flash
72   :compact:
73
74Sample Output
75*************
76
77.. code-block:: console
78
79   uart:~$
80     bypass              clear               date
81     demo                device              devmem
82     dynamic             help                history
83     kernel              log                 log_test
84     rem                 resize              retval
85     section_cmd         shell               shell_uart_release
86     stats               version
87   uart:~$ demo
88   demo - Demo commands
89   Subcommands:
90     dictionary  : Dictionary commands
91     hexdump     : Hexdump params command.
92     params      : Print params command.
93     ping        : Ping command.
94     board       : Show board name command.
95   uart:~$ dynamic
96   dynamic - Demonstrate dynamic command usage.
97   Subcommands:
98     add      : Add a new dynamic command.
99               Example usage: [ dynamic add test ] will add a dynamic command
100               'test'.
101               In this example, command name length is limited to 32 chars. You can
102               add up to 20 commands. Commands are automatically sorted to ensure
103               correct shell completion.
104     execute  : Execute a command.
105     remove   : Remove a command.
106     show     : Show all added dynamic commands.
107   uart:~$
108
109Details on Shell Subsystem
110==========================
111
112For more details on the Shell subsystem, check the general :ref:`Shell documentation <shell_api>`.
113