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
46This sample can be found under :zephyr_file:`samples/subsys/shell/shell_module`
47in the Zephyr tree.
48
49The sample can be built for several platforms.
50
51Emulation Targets
52=================
53
54The sample may run on emulation targets. The following commands build the
55application for the qemu_x86.
56
57.. zephyr-app-commands::
58   :zephyr-app: samples/subsys/shell/shell_module
59   :host-os: unix
60   :board: qemu_x86
61   :goals: run
62   :compact:
63
64After running the application, the console displays the shell interface, and
65shows the shell prompt, at which point the user may start the interaction.
66
67On-Hardware
68===========
69
70.. zephyr-app-commands::
71   :zephyr-app: samples/subsys/shell/shell_module
72   :host-os: unix
73   :board: nrf52840dk/nrf52840
74   :goals: flash
75   :compact:
76
77Sample Output
78*************
79
80.. code-block:: console
81
82   uart:~$
83     bypass              clear               date
84     demo                device              devmem
85     dynamic             help                history
86     kernel              log                 log_test
87     rem                 resize              retval
88     section_cmd         shell               shell_uart_release
89     stats               version
90   uart:~$ demo
91   demo - Demo commands
92   Subcommands:
93     dictionary  : Dictionary commands
94     hexdump     : Hexdump params command.
95     params      : Print params command.
96     ping        : Ping command.
97     board       : Show board name command.
98   uart:~$ dynamic
99   dynamic - Demonstrate dynamic command usage.
100   Subcommands:
101     add      : Add a new dynamic command.
102               Example usage: [ dynamic add test ] will add a dynamic command
103               'test'.
104               In this example, command name length is limited to 32 chars. You can
105               add up to 20 commands. Commands are automatically sorted to ensure
106               correct shell completion.
107     execute  : Execute a command.
108     remove   : Remove a command.
109     show     : Show all added dynamic commands.
110   uart:~$
111
112Details on Shell Subsystem
113==========================
114
115For more details on the Shell subsystem, check the general :ref:`Shell documentation <shell_api>`.
116