# 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`:

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