• Bibiman
  • TL;DR
  • Installation
  • Usage
  • Configuration
    • Location of Config File
    • General Configuration
    • Color Configuration
  • Features
  • Keybindings
  • Search
  • Edit bib entry
  • Open connected files or links
  • Issues and code improvement
  • Alternatives
    • Comparison

TL;DR

bibiman is a simple terminal user interface for handling your BibLaTeX database as part of a terminal-based scientific workflow.

Here's a small impression how it looks and works:

Installation

You can install bibiman directly from crates.io using cargo:

cargo install bibiman

To use the version including the newest commits, you can clone the repo and build it from source using cargo:

git clone https://codeberg.org/lukeflo/bibiman
cd bibiman

# Build the binary to /target/release
cargo build --release

# OR
# Install the binary to CARGO_HOME/bin which normally is in PATH
cargo install --path=. --locked

Usage

The following arguments are possible:

USAGE:
    bibiman [FLAGS] [files/dirs]

POSITIONAL ARGS:
    <file>    Path to .bib file
    <dir>     Path to directory containing .bib files

FLAGS:
    -h, --help          Show this help and exit
    -v, --version       Show the version and exit
    -c, --config-file=  Path to config file for current session needed as argument.
                        Takes precedence over standard config file 
    --light-terminal    Enable color mode for light terminal background

As seen, you can pass a single file, multiple files, the path of a directory containing bibfiles, or mix files and directories.

Directories will be searched recursively for files with the .bib extension and add them to the entry list. Other files will be ignored.Thus, be careful not to pass a directory with multiple subdirectories (like eg /home/usr/), because this could lead to some delay while parsing GBs of data.

The following lines are all valid CLI calls to run bibiman using the test files from the tests folder:

# single file
bibiman tests/biblatex-test.bib

# multiple files
bibiman tests/multi-files/bibfile1.bib tests/multi-files/bibfile2.bib

# directory containing bibfiles
bibman tests/multi-files/

# mixed arguments
bibiman tests/biblatex-test.bib tests/multi-files/

Configuration

Location of Config File

bibiman can be configured through a config file. The standard location is the user's config dir following the XDG scheme. On Linux systems this defaults to:

# XDG scheme:
$XDG_CONFIG_HOME/bibiman/bibiman.toml

# Fallback:
$HOME/.config/bibiman/bibiman.toml

You can set a custom config file through the CLI (-c/--config-file= flag) which takes precedence over the standard one for the active session:

bibiman --config-file="/path/to/temporary/config"

General Configuration

The following general values can be set through the config file:

[general]
# Default files/dirs which are loaded on startup
# Use absolute paths (~ for HOME works). Otherwise, loading might not work.
bibfiles = [ "/path/to/bibfile", "path/to/dir/with/bibfiles" ]
# Default editor to use when editing files. Arguments are possible
editor = "vim" # with args: "vim -y"
# Default app to open PDFs/Epubs
pdf_opener = "xdg-open"
# Default app to open URLs/DOIs
url_opener = "xdg-open"

If no file or dir is set as bibfiles value, you have to add a path via CLI interface. If the bibfiles value is set and a further path (or multiple) is provided through the CLI call, the entries of all those files will be opened in the started bibiman session.

Color Configuration

Furthermore, it is now possible to customize the colors. The following values can be changed:

[colors]
# Default values for dark-themed terminal
main_text_color = "250"
highlight_text_color = "254"
entry_color = "36"
keyword_color = "101"
info_color = "99"
confirm_color = "47"
warn_color = "124"
bar_bg_color = "234"
popup_bg_color = "234"
selected_row_bg_color = "237"

Colors can be set through three different methods: ANSI color names, 256-color indices and HEX codes. For example, the following definitions are all valid:

selected_row_bg_color = "darkgray" # ANSI color name (light_black or bright_black would also work)
selected_row_bg_color = "237" # 256-color index
selected_row_bg_color = "#3a3a3a" # HEX code

To run bibiman with some default values for a light-colored terminal use the --light-terminal flag.

Features

These are the current features, the list will be updated:

• Browse through the bib entries using Vim-like keybindings and a fuzzy search mode.
• Filter the bib entries by keywords (and afterwards filter further by fuzzy searching).
• Edit the current entry by opening a terminal-based editor at the specific line.
• Yank/Copy the citekey of the current entry to the system clipboard.
• Open related PDF file (file BibLaTeX key) with keypress.
• Open related URL/DOI with keypress.
• Scrollbar for better navigating.
• Sort Entries by column (Authors, Title, Year, Pubtype), or by position in bibfile.
• Load multiple files into one session.
• Add Entry via DOI.
• Implement config file for setting some default values like main bibfile, PDF-opener, or editor
• Open related notes file for specific entry.
• Support Hayagriva(.yaml) format as input (on hold for now, because the Hayagriva Yaml style doesn't offer keywords; s. issue in Hayagriva repo).

Please feel free to suggest further features through the issue functionality.

Keybindings

Use the following keybindings to manage the TUI:

Search

The search mode uses the nucleo-matcher crate. Thus, fuzzy searching is enabled by default. You can use some special chars to alter pattern matching:

• ^... matches literally at beginning of the string.
• ...$ matches literally at end of the string.
• '... matches literally everywhere in string.

Edit bib entry

The main editor can be set through the config file. Otherwise, the environment variables VISUAL and EDITOR will be used in this order. The last fallback solution is vi.

I've tested the following editors (set as value of VISUAL and through the config file):

• Helix: export VISUAL="hx"
• Vim/Neovim: export VISUAL="vim/nvim"
• Emacs (Terminal): export VISUAL="emacs -nw"
• Nano: export VISUAL="nano"
• Emacs (GUI): export VISUAL="emacs" (open emacs in separate window, blocks the terminal running bibiman as long as emacs is opened)

Feel free to try other editors and report. Important is that the editor supports the argument +.. to set the line number that the cursor should be placed at. Otherwise, the functionality might not work properly.

While this behaviour is most likely supported on UNIX-based systems (Linux, MacOS), it might not work under Windows. I can't test it on a Windows machine, thus, there might be unexpected errors with it.

Open connected files or links

bibiman also provides the possibility to open PDFs (as value of the file BibLaTeX field), as well as DOIs and URLs.

For selecting the right program, it uses xdg-open on Linux, open on MacOS, and start on Windows. Thanks to the report from @bastislack in #2 MacOS seems to work.

However, Windows does not work. Have to figure this out. Reports from some Windows users are very welcome.

Furthermore, DOIs have to begin with either https://doi... as full URL or 10.(...) as regular DOI style. URLs work if they begin with either http... or with www....

Issues and code improvement

This is my first Rust project and, thus, also a learning process. If you find any issues or code flaws, please open an issue.

Alternatives

bibiman is a project tailored to my personal needs. I use a single main file for all my bib entries and want to use bibiman mainly as kind of (terminal)-graphical wrapper for often emerging tasks, since I work in the terminal most of the time.

I used JabRef for many years, but its way to bloated in my eyes. There exists a bunch of other graphical tools...

But there are also some TUI alternatives with slightly different approaches. Maybe one of these might fit your personal needs better:

• bibman (Haskell): A very nice CLI program including a TUI I also used for some times. It has way more CLI features (export etc.) at the moment.
• bibman (Python): A TUI written in Python with focus on Zotero-like functions. If you're used to Zotero, this might be a good fit.
• bibman (Perl): A fast and simple TUI written in good ol' Perl. It looks like back in the days, but seems not being maintained anymore.
• cobib: Very elaborated bib manager with CLI and TUI functions.
• papis: Powerful CLI tool for managing bibliographies and documents. Has also some TUI features.

Comparison

I compared bibiman only free-hand to bibman (Haskell) and bibman (Perl), since there is no simple benchmark test for TUIs. At least, I couldn't find one.

Loading a test file containing 25.000 dummy entries as well as a directory containing 25.000 single dummy .bib files bibiman was significantly faster on startup than both other programs. The performance also did not suffer. Only on a test file with more than 50.000 dummy entries a very short delay after keypresses was recognizable when scrolling the entry list.

After all, bibiman is really fast and runs very smooth while having the most complex user interface by far compared to the other programs.