COBIB(1)

NAME
CoBib - Console-based Bibliography Management

SYNOPSIS
cobib [--version] [-h|--help] [-v|--verbose] [-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

--version
    Prints the version information and exits.

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

-v, --verbose
    Increases the verbosity level of the logging. This option may be provided up to two times (increasing the logging to info and debug, respectively). By default, the verbosity of CoBib's CLI is set to warning but if the TUI is started, logging will be increased to info and redirected to /tmp/cobib.log.

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

-l, --log <path>
    Run with an alternate log 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:

-g, --git
Initializes CoBib's integrated history tracking through git. This command will preserve any existing database file, but it is a good idea to make a backup before doing this, just in case. Note, that in order to use this functionality you must also enable the DATABASE/git configuration option (see also CONFIGURATION). Also be sure to at least set a name and email in the git config!

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.

-i, --isbn <doi>
Adds an entry specified by the ISBN.

-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.

-a, --add <path>
Allows editing a non-existing label to manually add it to the database.

cobib modify <modification> <args> ...
    Applies a modification to multiple entries at once. The positional arguments may be used to provide FILTERS which the entries must match in order to be modified or to provide a list of labels of the entries which are to be modified (this requires the -s flag to be set). The <args> may be any of the following:

<modification>
The modification must be provided in the format <field>:<value> and will set the field of all selected entries to the given value.

-a, --append
This is NOT implemented yet. However, in the future this will provide the possibility to append the new value to the modified field rather than overwriting it.

-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.

cobib undo <args>
    If you enabled the git-integration of CoBib (available since v2.6.0) you can undo the changes done to your database file by commands such as add, edit and delete. See also DATABASE/git in the CONFIGURATION section for more information.

-f, --force
Overwrites the check for an auto-committed change. Thus, the undo command will now undo the last commit with a message that does not start with "Undo".

cobib redo
    If you enabled the git-integration of CoBib (available since v2.6.0) you can reapply the last undone changes (see above). See also DATABASE/git in the CONFIGURATION section for more information.

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. 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
    Opens the current (or selected) label(s).

w wrap
    Toggles wrapping of the viewing buffer.

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

d delete
    Deletes the current (or selected) label(s).

e edit
    Opens the current label in an external editor.

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

u undo
    Undoes the last auto-committed change to the database file. This requires the git-integration (since v2.6.0) to be enabled!

r redo
    Reapplies the last undone change. This requires the git-integration (since v2.6.0) to be enabled!

/ search
    Opens a search prompt and views the results in the viewing buffer.

f filter
    Allows adding filters to the list view.

s sort
    Allows sorting the list view.

v select
    Adds the current label to the selection.

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.

: prompt
    Opens a command prompt allowing the user to execute an arbitrary CoBib CLI command.

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.

git=False
    This boolean field indicates whether the database file should automatically be tracked in a git repository. Note, that you must initialize the git-tracking with cobib init --git. If you already have an existing database file, it will be preserved. Nonetheless, it is a good idea to make a backup before doing so, just in case. Also be sure to at least set a name and email in the git config!

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