Nerves Runtime Shell

A custom shell for debugging and running commands on Nerves devices in a bash-like environment.

Nerves devices typically only expose an Elixir or Erlang shell prompt. While this is handy, some tasks are easier to run in a more bash-like shell environment. The nerves_runtime shell provides a limited CLI that can be run without leaving the Erlang runtime.

Here's an example of how to use access it:

iex(1)> [Ctrl+G]
User switch command
 --> s sh
 --> j
   1  {erlang,apply,[#Fun<Elixir.IEx.CLI.1.112225073>,[]]}
   2* {sh,start,[]}
 --> c
Nerves Interactive Command Shell

Type Ctrl+G to exit the shell and return to Erlang job control.
This is not a normal shell, so try not to type Ctrl+C.

/srv/erlang[1]>

There are a few caveats to using this shell for now:

1. For projects generated by nerves_bootstrap prior to v0.5.0, the default behavior of Ctrl+C Ctrl+C is to exit the Erlang VM and reboot or hang your system, depending on how erlinit is configured. For projects generated by nerves_bootstrap v0.5.0 or later, the rel/vm.args file has the +Bc option included, which allows the Erlang VM to respond to an interrupt generated by Ctrl+C:

   iex(1)> # Press CTRL+C
   iex(2)> ** (EXIT) interrupted
   
   iex(2)> :timer.sleep(1_000_000_000)
   ** (EXIT) interrupted
   iex(2)>
   User switch command
    --> s sh
    --> c
   Nerves Interactive Command Shell
   
   Type Ctrl+G to exit the shell and return to Erlang job control.
   This is not a normal shell, so try not to type Ctrl+C.
   
   /srv/erlang[1]> ls
   releases
   lib
   
   /srv/erlang[2]> Interrupted
   /srv/erlang[2]> Interrupted

2. If you want to upgrade an existing project to have this new behavior, simply add +Bc on a line before the -extra line in rel/vm.args. Or, as a workaround without making that change, start another shell using Ctrl+G and kill the offending program.

3. Commands are run asynchronously. This is unexpected if you're used to a regular shell. For most commands, it's harmless. One side effect is that if a command changes the current directory, it could be that the prompt shows the wrong path.

4. Starting the shell on a remote node (for example, using remsh) is not currently supported.

Installation

The package can be installed by adding nerves_runtime_shell to your list of dependencies in mix.exs:

def deps do
  [
    {:nerves_runtime_shell, "~> 0.1.0"}
  ]
end