The Elvish command

Table of content

1. Introduction

The Elvish command, elvish, 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.

2. Using Elvish interactively

Invoking Elvish with no argument runs it in interactive mode (unless there are flags that suppress this behavior). (To use Elvish as your default shell, see this page).

In this mode, Elvish runs a REPL (read-eval-print loop) that evaluates input continuously. The “read” part of the REPL is a rich interactive editor, and its API is exposed by the edit: module. Each unit of code read is executed as a code chunk.

2.1. RC file

Before the REPL starts, Elvish will execute the RC file. Its path is determined as follows:

  1. If the legacy ~/.elvish/rc.elv exists, it is used (this will be ignored starting from 0.21.0).

  2. If the XDG_CONFIG_HOME environment variable is defined and non-empty, $XDG_CONFIG_HOME/elvish/rc.elv is used.

  3. Otherwise, ~/.config/elvish/rc.elv (non-Windows OSes) or %AppData%\elvish\rc.elv (Windows) is used.

If the RC file doesn’t exist, Elvish does not execute any RC file.

2.2. Database file

Elvish in interactive mode uses a database file to keep command and directory history. Its path is determined as follows:

  1. If the legacy ~/.elvish/db exists, it is used (this will be ignored starting from 0.21.0).

  2. If the XDG_STATE_HOME environment variable is defined and non-empty, $XDG_STATE_HOME/elvish/db.bolt is used.

  3. Otherwise, ~/.local/state/elvish/db.bolt (non-Windows OSes) or %LocalAppData%\elvish\db.bolt is used.

3. Running a script

Invoking Elvish with one or more arguments will cause Elvish to execute a script (unless there are flags that suppress this behavior).

If the -c flag is given, the first argument is executed as a single code chunk.

If the -c 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.

The remaining arguments are put in $args.

When running a script, Elvish does not evaluate the RC file.

4. Module search directories

When importing modules, Elvish searches the following directories:

  1. If the XDG_CONFIG_HOME environment variable is defined and non-empty, $XDG_CONFIG_HOME/elvish/lib is searched.

    Otherwise, ~/.config/elvish/lib (non-Window OSes) or %RoamingAppData%\elvish\lib (Windows) is searched.

  2. If the XDG_DATA_HOME environment variable is defined and non-empty, $XDG_DATA_HOME/elvish/lib is searched.

    Otherwise, ~/.local/share/elvish/lib (non-Windows OSes) or %LocalAppData%\elvish\lib (Windows) is searched.

  3. If the XDG_DATA_DIRS environment variable is defined and non-empty, it is treated as a colon-delimited list of paths (semicolon-delimited on Windows), which are all searched.

    Otherwise, /usr/local/share/elvish/lib and /usr/share/elvish/lib are searched on non-Windows OSes. On Windows, no directories are searched.

  4. If the legacy ~/.elvish/lib directory exists, it is also searched (this will be ignored starting from 0.21.0).

5. Command-line flags

  • -buildinfo: Output information about the Elvish build and quit. See also -version and -json.

  • -c: Treat the first argument as code to execute, instead of name of file to execute. See running a script.

  • -compileonly: Parse and compile Elvish code without executing it. Useful for checking parse and compilation errors.

    Currently ignored when Elvish is run interactively (so can’t be used to check the RC file, for example).

  • -deprecation-level n: Show warnings for features deprecated as of version 0.n.

    In release builds, the default value matches the release version, and this flag is mainly useful for hiding newly introduced deprecation warnings. For example, if you have upgraded from 0.41 to 0.42, you can use -deprecation-level 41 to hide deprecation warnings introduced in 0.42, before you have time to fix those warnings.

    In HEAD builds, the default value matches the previous release version, and this flag is mainly useful for previewing upcoming deprecations. For example, if you are running a HEAD version between the 0.42.0 release and 0.43.0 release, you can use -deprecation-level 43 to preview deprecations that will be introduced in 0.43.0.

  • -help: Show usage help and quit.

  • -i: A no-op flag, introduced for POSIX compatibility. In future, this may be used to force interactive mode.

  • -json: Show the output from -buildinfo, -compileonly, or -version in JSON.

  • -log /path/to/log-file: Path to a file to write debug logs to.

  • -lsp: Run the builtin language server.

  • -norc: Don’t read the RC file when running interactively. The -rc flag is ignored if specified.

  • -rc /path/to/rc: Path to the RC file when running interactively. This can be useful for testing a new interactive configuration before installing it as your default config.

  • -version: Output the Elvish version and quit. See also -buildinfo and -json.

5.1. Daemon flags

The following flags are used by the storage daemon, a process for managing the access to the database. You shouldn’t need to use these flags unless you are debugging daemon functionalities.

  • -daemon: Run the storage daemon instead of an Elvish shell.

  • -db /path/to/db: Path to the database file. This only has effect when used together with -daemon, or when there is no existing daemon running.

  • -sock /path/to/socket: Path to the daemon’s UNIX socket. A non-daemon process will use this socket to send requests to the daemon, while a daemon process will listen on this socket.