COBIB(1)

NAME
CoBib - Console-based Bibliography Management

SYNOPSIS
cobib [-v|--version] [-h|--help] [-c|--config <path>] <subcommand> [<args>]

DESCRIPTION
CoBib is a console-based bibliography manager written in Python. It maintains a plain-text database of literature data in YAML format at $HOME/.local/share/cobib/literature.yaml.

CoBib provides a variety of SUBCOMMANDS through which you may investigate and manage the database. For easy of use it also comes with a curses-based TUI which is automatically started when no other subcommand is found (more information is provided in that section).

OPTIONS

-h, --help
    Prints a help message and exits.

-v, --version
    Prints the version information and exits.

-c, --config <path>
    Run with an alternate configuration file at <path>.

SUBCOMMANDS
All subcommands listed below also provide the -h and --help options which provide additional information for each subcommand.

cobib init <args>
    Initializes the literature database. The path to this file can be configured in the DATABASE section of the configuration file (see also CONFIGURATION). The only available argument is:

-f, --force
Forces the initialization, possibly overwriting any existing database file.

cobib add <args> ...
    Adds a new entry to the database. The positional arguments may be used to provide tags to associate with the newly added entries. The <args> may be any of the following:

-a, --arxiv <arxiv id>
Adds an entry specified by the arXiv id.

-b, --bibtex <path>
Adds the bibliography data from the BibLaTex file at the provided path.

-d, --doi <doi>
Adds an entry specified by the DOI.

-f, --file <path>
Associate the newly added entry with the file at the provided path. As of version 2.5 you can specify multiple files, too.

-l, --label <label>
Store the newly added entry under the specified label.

cobib delete <label>
    Deletes the entry with the given label.

cobib edit <label>
    Opens the entry with the given label in the $EDITOR. The entry is copied verbatim in YAML format from and to the database file.

cobib open <label>
    Opens any associated file of the entry with the given label. If multiple files are associated with the entry, the user can choose which file(s) to open through an interactive menu.

cobib show <label>
    Prints the entry with the given label in BibLaTex format to stdout.

cobib list <args>
    Lists all entries of the database in a basic table format to stdout which match the specified FILTERS (more information is provided in that section). Additionally, the following <args> are also allowed:

-l, --long
Print the table in long format, i.e. without wrapping the lines to fit the current terminal width.

-s, --sort <field>
Specify the entry field to use as the sorting column of the table.

-r, --reverse
Reverses the sorting order.

-x, --or
Concatenate the filters using logical OR rather than the default AND.

cobib search <args> ...
    Searches the database recursively (i.e. including any associated files) for the specified keyword. The positional arguments may be used to provide FILTERS which the entries must match in order to be included in the export. Additionally, the following <args> are also allowed:

-c, --context <int>
Specify the number of context lines to provide for each match. This values defaults to 1.

-i, --ignore-case
Makes the search case-insensitive.

cobib export <args> ...
    Exports the database to the file configured via the args. The positional arguments may be used to provide FILTERS which the entries must match in order to be included in the export or to provide a list of labels of the entries which are to be exported (this requires the -s flag to be set). The <args> may be any of the following:

-b, --bibtex <path>
Export the entries to a BibLaTex file at the specified path.

-z, --zip <path>
Export a BibLaTex file of the entries and all of the associated files into a single ZIP file at the specified path.

-s, --selection
This boolean flag enables the selection mode in which the positional args are interpreted as a list of labels which are to be exported. The name for this argument is a result of the TUI's selection interface.

FILTERS
In order to limit the output of the list and export commands you can apply additional filters via keyword arguments. Their availability depends on your database since they are added to the argument parser at runtime. However, you can find a full list for your specific case with cobib list --help.

The general syntax for filtering is the following
[++|--]<field> <value>
which is to be understood as the following: When the keyword argument is started with ++ the entry must positively match this filter; if started with -- it must NOT match. The <field> may be any available field in your database. It should be noted, that this string is matched exactly which means no plurals are allowed. The <value> finally specifies what is matched against.

In general, multiple filters provided to the list and export commands are combined with logical AND. This may be overwritten by adding the -x or --or arguments as described in the arguments section of the list command.

EXAMPLES
This section provides a few examples of FILTERS as described above.

cobib list ++year 2020
    Lists only entries which were published in 2020.

cobib list --tags chemistry
    Lists only entries without the `chemistry` tag.

cobib list ++year 2019 ++tags quantum
    Lists only entries with the `quantum` tag from the year 2019.

cobib list -x ++year 2019 ++year 2020
    Lists only entries published in 2019 or 2020.

TUI
The curses-based TUI is started automatically when no other subcommand is supplied, i.e. by simply running cobib. By default, it lists all entries of the database in a buffer which may be scrolled in vim-fashion with h,j,k,l,^B,^U,^D,^F. The arrow and paging keys are also available for scrolling. The following default key bindings are available:

q quit
    Quits one level of the viewing buffer.

? help
    Opens a small window providing help for the key bindings.

ENTER show
    Populates the viewing buffer with a BibLaTex view of the selected entry.

o open
    Respects the selection.

w wrap
    Toggles between long (default) and short (wrapped) list mode.

a add
    Opens a command prompt which allows running the add command as if outside of the TUI.

e edit

d delete
    Respects the selection.

/ search

f filter
    Allows adding filters to the list view.

s sort
    Allows sorting the list view.

v select

x export
    Opens a command prompt which allows running the export command as if outside of the TUI. If a selection is present, the -s argument will be set automatically.

CONFIGURATION
Cobib can be configured with an INI file placed at $HOME/.config/cobib/config.ini For more information on this file format take a look at https://docs.python.org/3/library/configparser.html This section summarizes the sections and respective configuration options.

[DATABASE]

file=$HOME/.local/share/cobib/literature.yaml
    Specifies the path to the database file.

open=xdg-open (on Linux); open (on Mac OS)
    Specifies the program used to open associated files.

grep=grep
    Specifies the program used to search in associated files.

search_ignore_case=False
    This boolean field indicates whether search defaults to be case-insensitive.

[FORMAT]

month=int
    This field may either be int (default) or str and it specifies the type into which the month field should be converted before storing.

ignore_non_standard_types=False
    This boolean field indicates whether non-standard BibLaTex entry types should be ignored or not.

default_entry_type=article
    This field indicates the default entry type which will be used for manually entered entries.

[TUI]

default_list_args=-l
    This field specifies the default arguments to use for the list view.

prompt_before_quit=True
    This field specifies whether the user is prompted to verify the final quit operation.

reverse_order=True
    This field specifies whether the database is listed in reverse order by default. This is useful because in this way the latest added entries will be at the top.

scroll_offset=3
    This field specifies the scrolling offset used to prevent the cursor line to coming too close to the ends of the screen while scrolling. The intent of this setting is to provide a similar behavior as the 'scrolloff' option available in Vim.

[KEY_BINDINGS]

In this section you may provide additional key bindings by specifying the name of the command to execute as the key and the key to bind the command to as its value.

[COLORS]

cursor_line_fg=white

cursor_line_bg=cyan

top_statusbar_fg=black

top_statusbar_bg=yellow

bottom_statusbar_fg=black

bottom_statusbar_bg=yellow

search_label_fg=blue

search_label_bg=black

search_query_fg=red

search_query_bg=black

popup_help_fg=white

popup_help_bg=green

popup_stdout_fg=white

popup_stdout_bg=blue

popup_stderr_fg=white

popup_stderr_bg=red

selection_fg=white

selection_bg=magenta

ENVIRONMENT

$EDITOR
    Specifies the editor program to use for the edit command.

FILES

$HOME/.config/cobib/config.ini
    The configuration file.

$HOME/.local/share/cobib/literature.yaml
    The default location of the database file.

SEE ALSO
The internal help documentation via the --help arguments.

The source code and issue tracker at https://gitlab.com/mrossinek/cobib