Command line reference manager with a single source of truth: the .bib file. Inspired by beets.

https://travis-ci.com/Nagasaki45/bibo.svg?branch=master

Links¶

Documentation: https://bibo.readthedocs.io/en/latest
Source code: https://github.com/Nagasaki45/bibo
PyPI releases: https://pypi.org/project/bibo
License: MIT

Content¶

Why bibo?¶

There are many reference managers out there, so why writing another one? bibo is different for a few reasons:

Your .bib and other files (e.g. pdfs) are exactly where you want them.
No need to export .bib files.
Enjoy the power of the command line.
Extensible with plugins.

Installation¶

Prerequisites¶

On linux, make sure to install xclip.
Optionally, define the EDITOR environment variable to an editor of your choice (this is usually already set on unix systems).
Optionally, for improved presentation, install bibtex.

`pip` installation¶

pip3 install bibo

On linux / mac you might need to prepend the above command with sudo for system wide installation, or, preferably, use the --user flag like this:

pip3 install --user bibo

For more information see the official packages installation guide.

Auto-complete¶

To activate auto-complete, if you’re using Bash add the following to your .bashrc

eval "$(_BIBO_COMPLETE=bash_source bibo)"

If you’re on zsh add this to your .zshrc

eval "$(_BIBO_COMPLETE=zsh_source bibo)"

Now, while in the middle of a command, press <TAB> to auto-complete options, arguments, or keys from your .bib database.

Quick start guide¶

bibo is a command line application, so some familiarity with the command line is assumed. Make sure you followed the installation first. Now, let’s dive in!

Setting up the database¶

When running bibo you should tell it where your .bib file is. It is commonly done by setting the BIBO_DATABASE environment variable. On unix, run the following (google for other OSs).

export BIBO_DATABASE=bibo_test.bib

Bibo will create the file when we start to add entries to it.

Adding entries¶

Now, copy the bibtex entry below to the clipboard:

@article{einstein1935can,
  title={Can quantum-mechanical description of physical reality be considered complete?},
  author={Einstein, Albert and Podolsky, Boris and Rosen, Nathan},
  journal={Physical review},
  volume={47},
  number={10},
  pages={777},
  year={1935},
  publisher={APS}
}

Let’s add this entry to bibo’s database.

bibo add

bibo will open your editor and paste the clipboard content to it. You are free to manually edit the raw entry. When ready, save and exit the editor.

We can also add entries by their digital object identifier (DOI).

bibo add --doi 10.1037/0033-295X.108.4.814

Again, save and exit.

Searching¶

bibo list Albert Einstein

will list all entries with the values ‘Albert’ and ‘Einstein’ in any field (or type / key). Try to search for the other entry we added by DOI, the one from Haidt.

Opening entries¶

Try running

bibo open haidt

It should open the browser and take you to the page where the DOI is pointing. Opening entries with a PDF file in their file field opens the PDF in your reader.

Where to go from here¶

We have only scratched the surface with the 3 most important commands of bibo: add, list, and open. You can discover the rest of the commands with

bibo --help

Each command also has a --help option. Don’t be scared to use it.

Manual¶

bibo¶

Command line reference manager with a single source of truth: the .bib file. Inspired by beets.

bibo [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

--database <database>¶: Required A path to a .bib file. Overrides the BIBO_DATABASE environment variable.

Environment variables

BIBO_DATABASE: Provide a default for --database

add¶

Add a new entry to the database.

Find a bib entry you would like to add. Copy it to the clipboard, and run the command. It will be opened in your editor for validation or manual editing. Upon saving, the entry is added to the database.

Don’t forget to set the EDITOR environment variable for this command to work properly.

bibo add [OPTIONS]

Options

--file <file>¶: Path to file to link to this entry.

--destination <destination>¶: A folder to put the file in.

--no-copy¶: Add the specified file in its current location without copying.

--doi <doi>¶: Add entry by DOI.

edit¶

Edit an entry.

Use FIELD_VALUE to set fields as follows: author=Einstein, or tags=interesting. Leave the value empty to open in editor. Set the key or type in the same way.

Don’t forget to set the EDITOR environment variable for this command to work properly.

bibo edit [OPTIONS] KEY [FIELD_VALUE]...

Options

--file <file>¶: Path to file to link to this entry.

--destination <destination>¶: A folder to put the file in.

--no-copy¶: Add the specified file in its current location without copying.

Arguments

KEY¶: Required argument

FIELD_VALUE¶: Optional argument(s)

list¶

List entries in the database.

A SEARCH_TERM matches an entry if it appears in the type, key, or any of the fields of the entry. If multiple search terms are provided an entry should match all of them. It is possible to match against a specific key, type, or field as follows: author:einstein, year:2018 or type:book. Note that search terms are case insensitive.

bibo list [OPTIONS] [SEARCH_TERM]...

Options

--raw¶: Format as raw .bib entries.

--bibstyle <bibstyle>¶: Bibtex bibliography style to use for citation formatting. For more information check https://www.overleaf.com/learn/latex/Bibtex_bibliography_styles.

--format <format>¶: Custom format pattern. Use $ in front of a key, type, or field to create custom formatter. For example: --format '$author ($year) - $title'.

--verbose¶: Show verbose information.

Arguments

SEARCH_TERM¶: Optional argument(s)

open¶

Open an entry in the database if a file, url, or doi field exists (with precedence in this order).

A file will be open by the application defined by your system according to the file extension. For example, a PDF should be opened by a PDF reader and a folder should be opened by a file browser. URLs and DOIs should be opened in the web browser

A SEARCH_TERM matches an entry if it appears in the type, key, or any of the fields of the entry. If multiple search terms are provided an entry should match all of them. It is possible to match against a specific key, type, or field as follows: author:einstein, year:2018 or type:book. Note that search terms are case insensitive.

This command fails if the number of entries that match the search is different than one.

bibo open [OPTIONS] [SEARCH_TERM]...

Arguments

SEARCH_TERM¶: Optional argument(s)

remove¶

Remove an entry from the database or remove a field from an entry.

To remove an entry specify its key. To fields specify the key and list all fields for removal.

bibo remove [OPTIONS] KEY [FIELD]...

Arguments

KEY¶: Required argument

FIELD¶: Optional argument(s)

Plugins¶

bibo is extensible with plugins. Here are some examples by the community:

bibo-todo: Plugin for bibo, mark entry as todo with optional note.
bibo-mark-read: A bibo plugin to mark that an entry was read.
bibo-check: A bibo plugin to check for mess in your files.

Send a pull request to add your bibo plugins to the list.

Contribution¶

Installing the development environment¶

Make sure the prerequisites are installed.

Then, preferably in a virtual environment, run

pip install -e .[dev]

Running tests¶

pytest

It automatically checks code formatting with black. If code formatting errors are detected they can be manually fixed, or try running black ..

Generating the documentation¶

cd docs
make html

To view the documentation, in a separate terminal, run

cd _build/html
python -m http.server

Now open your browser and go to http://localhost:8000.

Cleaning the docs is handy. Use

make clean

Commits and pull requests¶

Contributions to bibo are highly welcome! Please include tests for whatever you’re working on. Don’t worry about code coverage too much. Before commiting your changes make sure all tests pass.

Try to include the issue number in the commit message if relevant, as per this tutorial. Use #XXX to reference the issue or Fix #XXX if issue fixed by the commit.

Pull requests should be based on the dev branch.

Feel free to add yourself to the CONTRIBUTORS file 😊

Plugins development¶

Take a look at some of the existing plugins. They use the click-plugins library, so check out its documentation. Note that internal APIs in bibo (and the packages that are installed with it, like pybibs and click_constraints) will probably change quite a lot until bibo gets a stable release.

Links¶

Content¶

Why bibo?¶

Installation¶

Prerequisites¶

`pip` installation¶

Auto-complete¶

Quick start guide¶

Setting up the database¶

Adding entries¶

Searching¶

Opening entries¶

Where to go from here¶

Manual¶

bibo¶

add¶

edit¶

list¶

open¶

remove¶

Plugins¶

Contribution¶

Installing the development environment¶

Running tests¶

Generating the documentation¶

Commits and pull requests¶

Plugins development¶

bibo

Navigation

Related Topics

Links¶

Content¶

Why bibo?¶

Installation¶

Prerequisites¶

pip installation¶

Auto-complete¶

Quick start guide¶

Setting up the database¶

Adding entries¶

Searching¶

Opening entries¶

Where to go from here¶

Manual¶

bibo¶

add¶

edit¶

list¶

open¶

remove¶

Plugins¶

Contribution¶

Installing the development environment¶

Running tests¶

Generating the documentation¶

Commits and pull requests¶

Plugins development¶

`pip` installation¶