---
title: "Shell commands"
canonical_url: https://developer.repebble.com/pebbleos/docs/samples/subsys/shell/commands/
last_updated: 2026-11-18
sdk_version: 4.44
---
# Shell commands

Source: https://developer.repebble.com/pebbleos/docs/samples/subsys/shell/commands/

This sample registers [shell](https://developer.repebble.com/pebbleos/docs/subsystems/shell.md) commands: one whose argument count the shell checks, one with subcommands, and one that finishes later, returning `-EINPROGRESS` and calling `pbl_shell_cmd_done()` from a delayed work item.

To run them without anyone typing, the sample defines a shell of its own: a line shell, the kind a transport that carries whole commands implements. It submits each line with `pbl_shell_execute_line()`, prints the output to the standard output and waits for the `done` callback before the next. The console’s interactive shell has the same commands: type `help` at its prompt.

Run:

`pbl samples samples/subsys/shell/commands`

Boards:

every board

## Sources

src/main.c

```
#include \<errno.h\>#include \<stdio.h\>#include \<string.h\>#include \<pbl/kernel/sem.h\>#include \<pbl/kernel/time.h\>#include \<pbl/kernel/work.h\>#include \<pbl/shell/backend.h\>#include \<pbl/shell/shell.h\>#include \<pbl/util/size.h\>static bool s\_led;/\* A command with its argument count checked by the shell: a name, and an optional greeting. \*/static int prv\_cmd\_greet(const struct pbl\_shell \*sh, size\_t argc, char \*\*argv) {pbl\_shell\_print(sh, "%s, %s!", argc \> 2 ? argv[2] : "Hello", argv[1]);return 0;}PBL\_SHELL\_CMD\_ARG\_REGISTER(greet, nullptr, "Greet someone: greet \<name\> [greeting]", prv\_cmd\_greet,2, 1);/\* Subcommands; the parent has no handler, so on its own it prints them. \*/static int prv\_cmd\_led\_set(const struct pbl\_shell \*sh, size\_t argc, char \*\*argv) {s\_led = strcmp(argv[0], "on") == 0;pbl\_shell\_print(sh, "led is %s", s\_led ? "on" : "off");return 0;}static int prv\_cmd\_led\_toggle(const struct pbl\_shell \*sh, size\_t argc, char \*\*argv) {s\_led = !s\_led;pbl\_shell\_print(sh, "led is %s", s\_led ? "on" : "off");return 0;}static const struct pbl\_shell\_cmd s\_led\_cmds[] = {PBL\_SHELL\_CMD(off, nullptr, "Turn it off", prv\_cmd\_led\_set),PBL\_SHELL\_CMD(on, nullptr, "Turn it on", prv\_cmd\_led\_set),PBL\_SHELL\_CMD(toggle, nullptr, "Toggle it", prv\_cmd\_led\_toggle),PBL\_SHELL\_SUBCMD\_SET\_END,};PBL\_SHELL\_CMD\_REGISTER(led, s\_led\_cmds, "A pretend LED", nullptr);/\* A command that finishes later, without blocking the thread commands run on. \*/static const struct pbl\_shell \*s\_wait\_sh;static void prv\_wait\_done(struct pbl\_work \*work) {pbl\_shell\_print(s\_wait\_sh, "waited");pbl\_shell\_cmd\_done(s\_wait\_sh, 0);}static PBL\_DELAYED\_WORK\_DEFINE(s\_wait\_work, prv\_wait\_done);static int prv\_cmd\_wait(const struct pbl\_shell \*sh, size\_t argc, char \*\*argv) {unsigned long ms;int ret;ret = pbl\_shell\_strtoul(argv[1], &ms);if (ret \< 0) {pbl\_shell\_error(sh, "not a number: %s", argv[1]);return ret;}s\_wait\_sh = sh;pbl\_delayed\_work\_schedule(&pbl\_sys\_workq, &s\_wait\_work, PBL\_MSEC(ms));return -EINPROGRESS;}PBL\_SHELL\_CMD\_ARG\_REGISTER(wait, nullptr, "Finish after some milliseconds: wait \<ms\>", prv\_cmd\_wait,2, 0);/\* \* A line shell, the kind a transport that carries whole commands implements. Its output goes to \* the standard output, and the end of each command is signaled with a semaphore. \*/static PBL\_SEM\_DEFINE(s\_done, 0, 1);static int s\_ret;static void prv\_write(const struct pbl\_shell \*sh, const char \*data, size\_t len) {for (size\_t i = 0; i \< len; i++) {if (data[i] != '\r') {putchar(data[i]);}}}static void prv\_done(const struct pbl\_shell \*sh, int ret) {s\_ret = ret;pbl\_sem\_give(&s\_done);}static const struct pbl\_shell\_backend\_api s\_api = {.write = prv\_write,.done = prv\_done,};PBL\_SHELL\_DEFINE(s\_script, nullptr, &s\_api, nullptr);static const char \*const s\_lines[] = {"greet World", "greet Pebble Hi", "greet","led","led on","led toggle","led blink","wait 100", "wait soon", "beep",};int main(void) {for (size\_t i = 0; i \< ARRAY\_LENGTH(s\_lines); i++) {int ret;printf("shell\> %s\n", s\_lines[i]);ret = pbl\_shell\_execute\_line(&s\_script, s\_lines[i], strlen(s\_lines[i]));if (ret \< 0) {fprintf(stderr, "shell: command not submitted (%d)\n", ret);return ret;}(void)pbl\_sem\_take(&s\_done, PBL\_FOREVER);printf("shell: returned %d\n", s\_ret);}printf("Sample done\n");return 0;}
```

## Output

```
shell> greet World
Hello, World!
shell: returned 0
Hi, Pebble!
shell> greet$
error: greet: wrong parameter count
shell: returned -\d+
shell> led$
toggle +Toggle it
led is on
led is off
error: led: unknown subcommand 'blink'
shell> wait 100
waited
shell: returned 0
error: not a number: soon
error: beep: command not found, try 'help'
Sample done
```

Generated from PebbleOS [7753e801d](https://github.com/coredevices/pebbleos/commit/7753e801d93d20f2d37534ce2fa69d9952015237). This page is maintained in the pebbleos repository: [docs/samples/subsys/shell/commands.md](https://github.com/coredevices/pebbleos/blob/7753e801d93d20f2d37534ce2fa69d9952015237/docs/samples/subsys/shell/commands.md).
