1<!-- toc number-sections -->
2
3# Introduction
4
5The Elvish command, `elvish`, contains the Elvish shell and is the main way for
6using the Elvish programming language. This documentation describes its behavior
7that is not part of the [language](language.html) or any of the standard
8modules.
9
10# Using Elvish interactively
11
12Invoking Elvish with no argument runs it in **interactive mode** (unless there
13are flags that suppress this behavior).
14
15In this mode, Elvish runs a REPL
16([read-eval-print loop](https://en.wikipedia.org/wiki/Read–eval–print_loop))
17that evaluates input continuously. The "read" part of the REPL is a rich
18interactive editor, and its API is exposed by the [`edit:` module](edit.html).
19Each unit of code read is executed as a [code chunk](language.html#code-chunk).
20
21## RC file
22
23Before the REPL starts, Elvish will execute the **RC file**. Its path is
24determined as follows:
25
26-   If the legacy `~/.elvish/rc.elv` exists, it is used (this will be ignored in
27    a future version).
28
29-   Otherwise:
30
31    -   On UNIX (including macOS), `$XDG_CONFIG_HOME/elvish/rc.elv` is used,
32        defaulting to `~/.config/elvish/rc.elv` if `$XDG_CONFIG_HOME` is unset
33        or empty.
34
35    -   On Windows, `%AppData%\elvish\rc.elv` is used.
36
37If the RC file doesn't exist, Elvish does not execute any RC file.
38
39## Database file
40
41Elvish in interactive mode uses a database file to keep command and directory
42history. Its path is determined as follows:
43
44-   If the legacy `~/.elvish/db` exists, it is used (this will be ignored in a
45    future version).
46
47-   Otherwise:
48
49    -   On UNIX (including macOS), `$XDG_DATA_HOME/elvish/db.bolt` is used,
50        defaulting to `~/.local/state/elvish/db.bolt` if `$XDG_DATA_HOME` is
51        unset or empty.
52
53    -   On Windows, `%LocalAppData%\elvish\db.bolt` is used.
54
55# Running a script
56
57Invoking Elvish with one or more arguments will cause Elvish to execute a script
58(unless there are flags that suppress this behavior).
59
60If the `-c` flag is given, the first argument is executed as a single
61[code chunk](language.html#code-chunk).
62
63If the `-c` flag is not given, the first argument is taken as a filename, and
64the content of the file is executed as a single code chunk.
65
66The remaining arguments are put in [`$args`](builtin.html#args).
67
68# Module search directories
69
70When importing [modules](language.html#modules), Elvish searches the following
71directories:
72
73-   On UNIX:
74
75    1. `$XDG_CONFIG_HOME/elvish/lib`, defaulting to `~/.config/elvish/lib` if
76       `$XDG_CONFIG_HOME` is unset or empty;
77
78    2. `$XDG_DATA_HOME/elvish/lib`, defaulting to `~/.local/share/elvish/lib` if
79       `$XDG_DATA_HOME` is unset or empty;
80
81    3. Paths specified in the colon-delimited `$XDG_DATA_DIRS`, followed by
82       `elvish/lib`, defaulting to `/usr/local/share/elvish/lib` and
83       `/usr/share/elvish/lib` if `$XDG_DATA_DIRS` is unset or empty.
84
85-   On Windows: `%AppData%\elvish\lib`, followed by `%LocalAppData%\elvish\lib`.
86
87If the legacy `~/.elvish/lib` directory exists, it is also searched.
88
89# Other command-line flags
90
91Running `elvish -help` lists all supported command-line flags, which are not
92repeated here.
93