Magic Shell

"What was that long command I entered on my notebook last year that showed me all the installed packages?" If questions like these sound all too familiar, read on.

Unix shells such as Bash, Fish, or Zsh already have basic functions for reviewing the last commands typed at the command line. The up arrow key can be used to browse the command history, with each keystroke scrolling back one entry.

For commands that were executed a while ago, the Bash history function offers a little more information and convenience. The history function first appeared in Unix in 1978 in the C shell and spread from there to many command-line interpreters up to and including Microsoft's command.exe. A detailed manual [1] for the history function can be found on the DigitalOcean website (Figure 1).

Figure 1: The history command lists the commands typed at the command line. If you type an exclamation mark followed by the corresponding number, commands from the list can be executed again.

The Atuin [2] history tool takes this review function to the next level. Atuin replaces the existing shell history with an SQLite database, imports the previous history, provides more search options, and records additional context about the commands used in Atuin.

Atuin also synchronizes the recorded history to other devices on the network using end-to-end encryption via an external server. This feature allows users with multiple computers on their network to not only use the shell history of a single session or computer, but to also retrieve the entire history of all synchronized devices. Atuin currently supports the Bash, Fish, and Zsh shells.

Atuin is named after A'Tuin, the turtle that carries the Discworld through space in Sir Terry Pratchett's novels. Written in Rust, Atuin runs either as a client on the desktop or is self-hosted as a client-server application. If you choose the client-server option, synchronization will take place via your server; otherwise, a server belonging to the project is used. If you do not want to synchronize, you can disable the function (which is enabled by default) in the settings.

Installation

Some distributions include Atuin in their package sources, including Alpine Linux, Arch Linux, NixOS, and Manjaro. If you install Atuin via a distribution package, you then need to run three commands to write the required hooks to the .bashrc file (Listing 1).

$ curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh
$ echo , -f ~/.bash-preexec.sh  && source ~/.bash-preexec.sh' >> ~/.bashrc
$ echo ,eval "$(atuin init bash)"' >> ~/.bashrc

Users of Debian-based distributions can retrieve an up-to-date binary package of the current version 11 from Atuin's GitHub page [3]. For all other distributions, Atuin can be installed using a script (Figure 2) that you call as shown in line 1 of Listing 2.

01 $ bash <(curl https://raw.githubusercontent.com/ellie/atuin/main/install.sh)
02 [...]
03 $ atuin register -u <user> -e <email> -p <password>
04 $ atuin import auto
05 $ atuin sync
06 [...]
07 $ atuin login -u <User> -p <Password> -k <Key>

Figure 2: If you use the script, Atuin installs ready to use. If you use a binary package, some manual work is required.

Next, import the previous shell command history using the command:

atuin import auto

Atuin is now ready for use in this constellation. If you want to synchronize via the Atuin server, call the script and then run the commands shown in lines 3 to 5 of Listing 2.

Alternatively, a Docker image can be used to install on a server [4]. A Docker Compose file is available for easy rollout [5].

Configuration

Atuin creates files in two places in your home directory. The SQLite database can be found in .local/share/atuin/. You need to store the configuration file (Figure 3) in TOML format [6] in .config/atuin/. During synchronization, the encryption key is also stored in the ~/.local/share/atuin/ directory and can be retrieved using the atuin key command. You need this key to log into a synchronized machine using the command in line 7 of Listing 2.

Figure 3: Atuin is easily configured, but you need to decide whether or not to synchronize. The configuration specifies the official Atuin server for synchronization. If you are self-hosting, your server address must appear after sync_address.

Create the server.toml file for installation on a server in ~/.config/atuin/. In the configuration file for the client on the desktop, you can change the path to the database, disable synchronization, set the interval, and link to a separate server, among other things. The documentation specifies one hour as the synchronization frequency, but the configuration file sets sync_frequency to five minutes. If you set this to zero instead, Atuin synchronizes after each command.

For search mode, you can choose between the prefix, fulltext, and fuzzy options, with prefix as the default. The full text search works like a search engine and tries to identify the closest match to the search term. The developers describe the fuzzy search syntax in the documentation [7].

You can additionally set up a filter mode [8] for the search using the GLOBAL, HOST, SESSION, and DIRECTORY options, which will narrow down the results accordingly.

For some initial orientation regarding the available options, use the help command atuin --help in the usual way. In the simplest case, calling atuin search will return the desired results (Figure 4).

Figure 4: In normal mode, you can specify the keyword for the search when you call Atuin.

Interactive Mode

Atuin offers an interactive mode, which you enter by typing

atuin search -i

and exit by pressing Ctrl+C. If you don't specify any other arguments, the command shows the history of the commands entered, with the last command entered at the bottom of the list (Figure  5). The number of commands shown depends on the specification for HISTFILESIZE in .bashrc, with the number of stored commands limited to 500 by default.

Figure 5: Interactive mode reveals how many commands are displayed in the top right-hand corner. In the input line at the bottom, you can change the filter and limit the search by entering strings.

Use the mouse wheel or arrow keys to move through the list of commands. The numbers to the left of the commands let you jump directly to the respective command by pressing Alt+Number. Before each command, Atuin also shows you the length of a command's runtime. At the bottom of the window, an input line allows you to limit the output using keywords (Figure 6). If you enter apt in the input line, for example, only commands that contain this keyword will appear.

Figure 6: Entering d in the input line restricts the output to commands that start with that letter. You can press Ctrl+R to further limit GLOBAL's filter mode.

In Figure 6, you will see the default GLOBAL filter specification on the far left of the input line. GLOBAL displays the commands from all synchronized histories. You can press Ctrl+R or type HOST to limit the filter to the computer you are currently using, type SESSION for just the current session, or type DIRECTORY for commands called from the current working directory.