.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-command" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.SH Introduction
.PP
The Elvish command, \f[C]elvish\f[R], contains the Elvish shell and is
the main way for using the Elvish programming language.
This documentation describes its behavior that is not part of the
language or any of the standard modules.
.SH Using Elvish interactively
.PP
Invoking Elvish with no argument runs it in \f[B]interactive mode\f[R]
(unless there are flags that suppress this behavior).
.PP
In this mode, Elvish runs a REPL (read-eval-print loop) that evaluates
input continuously.
The \[lq]read\[rq] part of the REPL is a rich interactive editor, and
its API is exposed by the \f[C]edit:\f[R] module.
Each unit of code read is executed as a code chunk.
.SS RC file
.PP
Before the REPL starts, Elvish will execute the \f[B]RC file\f[R].
Its path is determined as follows:
.IP \[bu] 2
If the legacy \f[C]\[ti]/.elvish/rc.elv\f[R] exists, it is used (this
will be ignored in a future version).
.IP \[bu] 2
Otherwise:
.RS 2
.IP \[bu] 2
On UNIX (including macOS), \f[C]$XDG_CONFIG_HOME/elvish/rc.elv\f[R] is
used, defaulting to \f[C]\[ti]/.config/elvish/rc.elv\f[R] if
\f[C]$XDG_CONFIG_HOME\f[R] is unset or empty.
.IP \[bu] 2
On Windows, \f[C]%AppData%\[rs]elvish\[rs]rc.elv\f[R] is used.
.RE
.PP
If the RC file doesn\[cq]t exist, Elvish does not execute any RC file.
.SS Database file
.PP
Elvish in interactive mode uses a database file to keep command and
directory history.
Its path is determined as follows:
.IP \[bu] 2
If the legacy \f[C]\[ti]/.elvish/db\f[R] exists, it is used (this will
be ignored in a future version).
.IP \[bu] 2
Otherwise:
.RS 2
.IP \[bu] 2
On UNIX (including macOS), \f[C]$XDG_DATA_HOME/elvish/db.bolt\f[R] is
used, defaulting to \f[C]\[ti]/.local/state/elvish/db.bolt\f[R] if
\f[C]$XDG_DATA_HOME\f[R] is unset or empty.
.IP \[bu] 2
On Windows, \f[C]%LocalAppData%\[rs]elvish\[rs]db.bolt\f[R] is used.
.RE
.SH Running a script
.PP
Invoking Elvish with one or more arguments will cause Elvish to execute
a script (unless there are flags that suppress this behavior).
.PP
If the \f[C]-c\f[R] flag is given, the first argument is executed as a
single code chunk.
.PP
If the \f[C]-c\f[R] flag is not given, the first argument is taken as a
filename, and the content of the file is executed as a single code
chunk.
.PP
The remaining arguments are put in \f[C]$args\f[R].
.SH Module search directories
.PP
When importing modules, Elvish searches the following directories:
.IP \[bu] 2
On UNIX:
.RS 2
.IP "1." 3
\f[C]$XDG_CONFIG_HOME/elvish/lib\f[R], defaulting to
\f[C]\[ti]/.config/elvish/lib\f[R] if \f[C]$XDG_CONFIG_HOME\f[R] is
unset or empty;
.IP "2." 3
\f[C]$XDG_DATA_HOME/elvish/lib\f[R], defaulting to
\f[C]\[ti]/.local/share/elvish/lib\f[R] if \f[C]$XDG_DATA_HOME\f[R] is
unset or empty;
.IP "3." 3
Paths specified in the colon-delimited \f[C]$XDG_DATA_DIRS\f[R],
followed by \f[C]elvish/lib\f[R], defaulting to
\f[C]/usr/local/share/elvish/lib\f[R] and
\f[C]/usr/share/elvish/lib\f[R] if \f[C]$XDG_DATA_DIRS\f[R] is unset or
empty.
.RE
.IP \[bu] 2
On Windows: \f[C]%AppData%\[rs]elvish\[rs]lib\f[R], followed by
\f[C]%LocalAppData%\[rs]elvish\[rs]lib\f[R].
.PP
If the legacy \f[C]\[ti]/.elvish/lib\f[R] directory exists, it is also
searched.
.SH Other command-line flags
.PP
Running \f[C]elvish -help\f[R] lists all supported command-line flags,
which are not repeated here.