Elixir's interactive shell.

Some of the functionalities described here will not be availabledepending on your terminal. In particular, if you get a messagesaying that the smart terminal could not be run, some of thefeatures described here won't work.

Helpers

IEx provides a bunch of helpers. They can be accessed by typingh() into the shell or as a documentation for theIEx.Helpers module.

Autocomplete

To discover a module's public functions or other modules, type the module namefollowed by a dot, then press tab to trigger autocomplete. For example:

Enum.

A module may export functions that are not meant to be used directly:these functions won't be autocompleted by IEx. IEx will not autocompletefunctions annotated with@doc false,@impl true, or functions thataren't explicitly documented and where the function name is in the formof__foo__.

Autocomplete is available by default on Windows shells from Erlang/OTP 26.

Encoding and coloring

IEx expects inputs and outputs to be in UTF-8 encoding. This is thedefault for most Unix terminals but it may not be the case on Windows.If you are running on Windows and you see incorrect values printed,you may need to change the encoding of your current session by runningchcp 65001 before callingiex (or before callingiex.bat if usingPowerShell).

Similarly, ANSI coloring is enabled by default on most Unix terminals.They are also available on Windows consoles from Windows 10 and onErlang/OTP 26 or later. For earlier Erlang/OTP versions, you canexplicitly enable it for the current user in the registry by runningthe following command:

$reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

After running the command above, you must restart your current console.

Shell history

It is possible to get shell history by passing some options that enable itin the VM. This can be done on a per-need basis when starting IEx:

$iex --erl "-kernel shell_history enabled"

If you would rather enable it on your system as a whole, you can usetheERL_AFLAGS environment variable and make sure that it is setaccordingly on your terminal/shell configuration.

On Unix-like / Bash:

$export ERL_AFLAGS="-kernel shell_history enabled"

On Windows:

$set ERL_AFLAGS "-kernel shell_history enabled"

On Windows 10 / PowerShell:

$$env:ERL_AFLAGS = "-kernel shell_history enabled"

Expressions in IEx

As an interactive shell, IEx evaluates expressions. This has someinteresting consequences that are worth discussing.

The first one is that the code is truly evaluated and not compiled.This means that any benchmarking done in the shell is going to haveskewed results. So never run any profiling nor benchmarks in the shell.

Second, IEx allows you to break an expression into many lines,since this is common in Elixir. For example:

iex(1)>"ab...(1)>c""ab\nc"

In the example above, the shell will be expecting more input until itfinds the closing quote. Sometimes it is not obvious which characterthe shell is expecting, and the user may find themselves trapped inthe state of incomplete expression with no ability to terminate it otherthan by exiting the shell.

For such cases, there is a special break-trigger (#iex:break) that whenencountered on a line by itself will force the shell to break out of anypending expression and return to its normal state:

iex(1)>["ab...(1)>c"...(1)>"...(1)>]...(1)>#iex:break** (TokenMissingError) iex:1: incomplete expression

Pasting multiline expressions into IEx

IEx evaluates its input line by line in an eager fashion. If at the end of aline the code seen so far is a complete expression, IEx will evaluate it atthat point.

iex(1)>[1,[2],3][1,[2],3]

To prevent this behavior breaking valid code where the subsequent linebegins with a binary operator, such as|>/2 or++/2 , IEx automaticallytreats such lines as if they were prepended withIEx.Helpers.v/0, whichreturns the value of the previous expression, if available.

iex(1)>[1,[2],3][1,[2],3]iex(2)>|>List.flatten()[1,2,3]

The above is equivalent to:

iex(1)>[1,[2],3][1,[2],3]iex(2)>v()|>List.flatten()[1,2,3]

If there are no previous expressions in the history, the pipe operator willfail:

iex(1)>|>List.flatten()** (RuntimeError) v(-1) is out of bounds

If the previous expression was a match operation, the pipe operator will alsofail, to prevent an unsolicited break of the match:

iex(1)>x=42iex(2)>|>IO.puts()** (SyntaxError) iex:2:1: pipe shorthand is not allowed immediately after a match expression in IEx. To make it work, surround the whole pipeline with parentheses ('|>')    |2||>IO.puts()|^

Note, however, the above does not work for+/2 and-/2, as theyare ambiguous with the unary+/1 and-/1:

iex(1)>11iex(2)>+22

The BREAK menu

Inside IEx, hittingCtrl+C will open up theBREAK menu. In thismenu you can quit the shell, see process and ETS tables informationand much more.

Exiting the shell

There are a few ways to quit the IEx shell:

• via theBREAK menu (available viaCtrl+C) by typingq, pressing enter
• by hittingCtrl+C,Ctrl+C
• by hittingCtrl+\

If you are connected to remote shell, it remains alive after disconnection.

dbg and breakpoints

IEx integrates withKernel.dbg/2 and introduces a backend thatcan pause code execution. To enable it, you must pass--dbg pry:

$iex --dbg pry

For example, take the following function:

defmy_fun(arg1,arg2)dodbg(arg1+arg2)...implementation...end

When the code is executed withiex (most often by callingiex --dbg pry -S mix), it will ask you permission to use "pry".If you agree, it will start an IEx shell in the context of the functionabove, with access to its variables, imports, and aliases. However,you can only access existing values, it is not possible to accessprivate functions nor change the execution itself (hence the name"pry").

When using|> dbg() at the end of a pipeline, you can pry eachstep of the pipeline. You can typen whenever you want to jumpinto the next pipe. Typecontinue when you want to execute allof the steps but stay within the pried process. Typerespawn whenyou want to leave the pried process and start a new shell.

Alternatively, you can start a pry session directly, withoutdbg/2by callingIEx.pry/0.

IEx also allows you to set breakpoints to start pry sessionson a given module, function, and arity you have no control ofviaIEx.break!/4. Similar to pipelines indbg(),IEx.break!/4allows you to debug a function line by line and access its variables.However, breakpoints do not contain information about imports andaliases from the source code.

When usingdbg or breakpoints with tests, remember to pass the--trace tomix test to avoid running into timeouts:

$iex -S mix test --trace$iex -S mix test path/to/file:line --trace

The User switch command

Besides theBREAK menu, one can typeCtrl+G to get to theUser switch command menu. When reached, you can typeh toget more information.

In this menu, developers are able to start new shells andalternate between them. Let's give it a try:

Userswitchcommand-->siex-->c

The command above will start a new shell and connect to it.Create a new variable calledhello and assign some value to it:

hello=:world

Now, let's roll back to the first shell:

Userswitchcommand-->c1

Now, try to access thehello variable again:

hello** (CompileError) undefined variable "hello"

The command above fails because we have switched shells.Since shells are isolated from each other, you can't access thevariables defined in one shell from the other one.

TheUser switch command can also be used to terminate an existingsession, for example when the evaluator gets stuck in an infiniteloop or when you are stuck typing an expression:

Userswitchcommand-->i-->c

TheUser switch command menu also allows developers to connect toremote shells using ther command. A topic which we will discuss next.

Remote shells

IEx allows you to connect to another node in two fashions.First of all, we can only connect to a shell if we give namesboth to the current shell and the shell we want to connect to.

Let's give it a try. First, start a new shell:

$iex --sname fooiex(foo@HOST)1>

The string between the parentheses in the prompt is the nameof your node. We can retrieve it by calling thenode/0function:

iex(foo@HOST)1>node():"foo@HOST"iex(foo@HOST)2>Node.alive?()true

For fun, let's define a simple module in this shell too:

iex(foo@HOST)3>defmoduleHellodo...(foo@HOST)3>defworld,do:"it works!"...(foo@HOST)3>end

Now, let's start another shell, giving it a name as well:

$iex --sname bariex(bar@HOST)1>

If we try to dispatch toHello.world/0, it won't be availableas it was defined only in the other shell:

iex(bar@HOST)1>Hello.world()** (UndefinedFunctionError) undefined function Hello.world/0

However, we can connect to the other shell remotely. Open uptheUser switch command prompt (Ctrl+G) and type:

Userswitchcommand-->r'foo@HOST''Elixir.IEx'-->c

Now we are connected into the remote node, as the prompt shows us,and we can access the information and modules defined over there:

iex(foo@HOST)1>Hello.world()"it works!"

In fact, connecting to remote shells is so common that we providea shortcut via the command line as well:

$iex --sname baz --remsh foo@HOST

Where "remsh" means "remote shell". In general, Elixir supports:

• remsh from an Elixir node to an Elixir node
• remsh from a plain Erlang node to an Elixir node (through the ^G menu)
• remsh from an Elixir node to a plain Erlang node (and get anerl shell there)

Connecting an Elixir shell to a remote node without Elixir isnot supported.

The .iex.exs file

When starting, IEx looks for a configured path, then for a local.iex.exs file(located in the current working directory), then for a global.iex.exs filelocated inside the directory pointed by theIEX_HOME environment variable(which defaults to~) and loads the first one it finds (if any).

The code in the chosen.iex.exs file is evaluated line by line in the shell'scontext, as if each line were being typed in the shell. For instance, any modulesthat are loaded or variables that are bound in the.iex.exs file will be availablein the shell after it has booted.

Take the following.iex.exs file:

# Load another ".iex.exs" fileimport_file("~/.iex.exs")# Import some module from lib that may not yet have been definedimport_if_available(MyApp.Mod)# Print something before the shell startsIO.puts("hello world")# Bind a variable that'll be accessible in the shellvalue=13

Running IEx in the directory where the above.iex.exs file is locatedresults in:

$iexErlang/OTP 24 [...]hello worldInteractive Elixir - press Ctrl+C to exit (type h() ENTER for help)iex(1)> value13

It is possible to load another file by configuring theiex application'sdot_iexvalue (config :iex, dot_iex: "PATH" orIEx.configure(dot_iex: "PATH"))or supplying the--dot-iex option to IEx. Seeiex --help.

In case of remote nodes, the location of the.iex.exs files are takenrelative to the user that started the application, not to the user thatis connecting to the node in case of remote IEx connections.

Configuring the shell

There are a number of customization options provided by IEx. Take a lookat the docs for theIEx.configure/1 function by typingh IEx.configure/1.

Those options can be configured in your project configuration file or globallyby callingIEx.configure/1 from your~/.iex.exs file. For example:

# .iex.exsIEx.configure(inspect:[limit:3])

Now run the shell:

$iexErlang/OTP 24 [...]Interactive Elixir - press Ctrl+C to exit (type h() ENTER for help)iex(1)> [1, 2, 3, 4, 5][1, 2, 3, ...]