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 textual-based TUI which is automatically started when no other subcommand is found (more information is provided in that section).

coBib also provides some "meta"-commands. These are expained in the SHELL UTILITIES 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 config.logging.logfile.

-p, --porcelain
    Switches the output that will be printed to the terminal to "porcelain" mode. This is meant to be useful for parsing and testing purposes.

-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 <ISBN>
Adds an entry specified by the ISBN.

--url <URL>
Attempts to extract an entry from the <URL>.

-y, --yaml <path>
Adds the bibliography data from the YAML file at the provided path. The only supported YAML format is that of a coBib database file.

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

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

-p, --path <path>
Overwrites the location for the automatically downloaded file. If not specified, this setting defaults to config.utils.file_downloader.default_location.

--disambiguation <reply>
Sets the reply for the interactive prompt if an addition needs to be disambiguated. The possible values for <reply> are the following:
keep to keep the existing entry
replace to replace the existing entry
update to update the existing entry
disambiguate to disambiguate the new label from the existing one by adding a label suffix (see also config.database.format.label_suffix)

--skip-download
Skips attempting to automatically download an associated file for the entry. This takes precedence over the config.commands.add.skip_download setting.

--force-download
Forces attempting to automatically download an associated file for the entry. This takes precedence over the config.commands.add.skip_download setting.

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

--preserve-files
If specified, associated files will be preserved and not deleted. This takes precedence over the config.commands.delete.preserve_files setting.

--no-preserve-files
If specified, associated files will not be preserved. This takes precedence over the config.commands.delete.preserve_files setting.

cobib edit <label>
    Opens the entry with the given label in an external editor. The entry is copied verbatim in YAML format from and to the database file. The editor respects the $EDITOR environment variable unless overwritten by config.commands.edit.editor. It will fallback to vim if neither is configured.

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

--preserve-files
If specified, associated files will be preserved and not be renamed if the edit happens to rename the entry. This takes precedence over the config.commands.edit.preserve_files setting.

--no-preserve-files
If specified, associated files will not be preserved and be renamed if the edit happens to rename the entry. This takes precedence over the config.commands.edit.preserve_files setting.

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. As of v3.2.0 the <value> is interpreted as an "f"-string. This means you can even use placeholder variables and perform simple operations on them. The available variables depend on the entry which you are modifying as they are inferred from its stored data. For more information on "f"-strings refer to section 2.4.3 of https://docs.python.org/3/reference/lexical_analysis.html

--dry
When this flag is given, the modify command runs in dry mode. This means, the applied modifications are printed to stdout rather than applied directly. This allows easy prototyping of modifications to prevent errors during large bulk modifications.

-a, --add
Specifying this flag will add the modification's value to the specified field of the entry rather than overwriting it. In doing so, strings will be concatenated withOUT any spaces, lists will be appended to, numbers will be added, and anything else will be converted to a string field. If the field did not exist previously, it will simply be initialized with the new value.

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

--preserve-files
If specified, associated files will be preserved and not be renamed if the modification happens to rename the entry. This takes precedence over the config.commands.modify.preserve_files setting.

--no-preserve-files
If specified, associated files will not be preserved and be renamed if the modification happens to rename the entry. This takes precedence over the config.commands.modify.preserve_files setting.

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:

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

-r, --reverse
Reverses the sorting order.

-i, --ignore-case
Makes the entry matching case-insensitive. This takes precedence over the config.commands.list_.ignore_case setting.

-I, --no-ignore-case
Makes the entry matching case-sensitive. This takes precedence over the config.commands.list_.ignore_case setting.

-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 keywords (if multiple are given, these will be search independently). 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. The default value is 1 but can be configured via config.commands.search.context.

-i, --ignore-case
Makes the search case-insensitive. This takes precedence over the config.commands.search.ignore_case setting.

-I, --no-ignore-case
Makes the search case-insensitive. This takes precedence over the config.commands.list_.ignore_case setting.

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.

-a, --abbreviate
Causes all Journal names to be abbreviated. For this option to take effect, a list of abbreviations must be configured via config.utils.journal_abbreviations.

--dotless
Works in conjunction with the abbreviate argument in order to remove punctuation from the journal abbreviations.

cobib import <args> ...
    Imports entries from another bibliography manager. You usually only need to run this command once. The <args> may be any of the following:

--skip-download
Skips downloading of attachments encountered during the library import. This takes precedence over the config.commands.import_.skip_download setting.

--force-download
Forces downloading of attachments encountered during the library import. This takes precedence over the config.commands.import_.skip_download setting.

Furthermore you can specify one of the following sources from which to import your library. Each of those sources can optionally take further arguments via positional arguments following a -- separator.

--zotero -- <args>
The <args> may be any of the following:

--no-cache
Disabling loading or storing of cached OAuth authentication tokens.

--user-id <user ID>
Provide a custom Zotero user ID. If this is a publicly accessible library, no API key is required. Otherwise you must also use the following argument.

--api-key <API key>
Provide a custom Zotero API key.

FILTERS
In order to limit the output of the list, modify, search, 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. As of version v3.2.0 this value gets interpreted as a regex pattern, enabling powerful filter matching.

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 textual-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 scrollable view and displays the bibtex-representation of the entry under the cursor in a side panel. You can scroll using vim-like keybindings h,j,k,l or the arrow keys. The following key bindings are available:

q quit
    Quits the TUI.

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

_ layout
    Toggles between a horizontally and vertically split layout.

SPACE folds
    When displaying search results, toggles the visibility of any tree node.

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

v select
    Adds the current label to the selection.

/ search
    Opens a search prompt and views the results in an interactive tree structure.

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.

f filter
    Allows adding filters to the list of displayed entries.

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

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.

o open
    Opens the current (or selected) label(s).

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

s sort
    Allows sorting the list view.

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

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. Opens a small window providing help for the key bindings.

CONFIGURATION
Since version 3.0, coBib can be configured directly via Python. To do so, you must place the configuration file at $HOME/.config/cobib/config.py. If you don't have a configuration file yet, you can get started by copying the well-documented example configuration to the right location via:
    cobib _example_config > ~/.config/cobib/config.py
If you do have an old configuration file (prior to v3.0) and would like some guidance on how to migrate it, please read this short blog post of mine: https://mrossinek.gitlab.io/programming/cobibs-new-configuration/

Since v3.5, coBib also respects the COBIB_CONFIG environment variable. With this you can either specify a custom path to your configuration file or disable the loading of a configuration file entirely by setting it to one of the following values: "", 0, "f", "false", "nil", "none".

The following section summarizes the syntax and all possibly settings, for completeness.

Configuration Syntax
    Internally, coBib's configuration is nothing but a (nested) Python dataclass. Thus, after importing the config with
        from cobib.config import config
    it is very straight forward to change any setting by simply changing the value of an attribute. For example:
        config.database.git = True

LOGGING

config.logging.cache='~/.cache/cobib/cache'
    This settings sets the path to the default cache file.

config.logging.logfile='~/.cache/cobib/cobib.log'
    This setting sets the path to the default logfile. This setting can be overwritten at runtime using the --logfile command-line argument.

config.logging.version='~/.cache/cobib/version'
    In this file, the last run version of coBib gets cached. After an update, coBib automtically prints the newest section of the Changelog. To disable this functionality entirely, set this option to None.

COMMANDS

config.commands.add.skip_download=False
    Specifies whether to skip the attempt of downloading PDF files of added entries.

config.commands.delete.confirm=True
    Specifies whether or not to prompt for confirmation before deleting an entry.

config.commands.delete.preserve_files=False
    Specifies whether associates files should be preserved during deletion.

config.commands.edit.default_entry_type='article'
    This setting indicates the default entry type which will be used for manually entered entries.

config.commands.edit.editor=$EDITOR if available else 'vim'
    This setting can be used to overwrite the external editor used for manual editing of database entries. It defaults to the environment variable $EDITOR and falls back to vim if that is not set either.

config.commands.edit.preserve_files=False
    Specifies whether associates files should be preserved during renaming.

config.commands.import_.skip_download=False
    Specifies whether to skip downloading of attachments encountered during the library import.

config.commands.list_.default_columns=['label', 'title']
    Specifies the default columns displayed during the list command.

config.commands.list_.ignore_case=False
    Specifies whether filter matching should be performed case-insensitive.

config.commands.modify.preserve_files=False
    Specifies whether associates files should be preserved during renaming.

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

config.commands.open.fields=['file', 'url']
    Specifies the names of the data fields which are to be checked for openable URLs.

config.commands.search.context=1
    Specifies the default number of context lines to provide for each search query match.

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

config.commands.search.grep_args=[]
    Allows the specification of additional arguments for the grep command.

config.commands.search.ignore_case=False
    This boolean setting indicates whether search defaults to be case-insensitive.

config.commands.search.highlights.label='blue'
    Specifies the color used to highlight the entry labels when displaying search rsults.

config.commands.search.highlights.label='red'
    Specifies the color used to highlight the query matches when displaying search rsults.

DATABASE

config.database.file='~/.local/share/cobib/literature.yaml'
    This setting sets the path to the database file. You can use ~ to represent your $HOME directory.

config.database.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!

config.database.format.label_default='{label}'
    This field specifies the default label format in an f-string modification style as interpreted by the modify command. The default setting leaves the label unchanged from the import resource proposal. A simple example which uses the first authors surname and year is '{author.split()[1]}{year}'.

config.database.format.label_suffix=('_', LabelSuffix.ALPHA)
    This field specifies the default label disambiguator. The option takes a tuple of length 2, where the first entry is the string separating the proposed label from the disambiguator and the second one is one of the enumerators provided by config.LabelSuffix.

config.database.format.suppress_latex_warnings=True
    This boolean field indicates whether latex warnings will be ignored during the escaping of special characters.

Some fields are internally stored as lists. Upon conversion to the BibTeX
    format, these need to be converted to a basic string. In this process the entries of the list will be joined using the separators configured by the following settings.

config.database.stringify.list_separator.file=', '

config.database.stringify.list_separator.tags=', '

config.database.stringify.list_separator.url=', '

PARSERS

config.parsers.bibtex.ignore_non_standard_types=False
    This boolean setting indicates whether non-standard BibLaTex entry types should be ignored or not.

config.parsers.yaml.use_c_lib_yaml=True
    This boolean setting indicates whether to use the C-based implementation of the YAML parser. For this to work, additional packages may need to be installed. Read https://yaml.readthedocs.io/en/latest/install.html#optional-requirements for more details.

UTILS

config.utils.file_downloader.default_location='~/.local/share/cobib'
    This setting sets the default location for any downloaded associated files.

config.utils.file_downloader.url_map={}
    You can provide rules to map from a journal's landing page URL to its PDF URL. To do so, you must insert an entry into the following dictionary, with a regex-pattern matching the journal's landing page URL and a value being the PDF URL. E.g.:
        config.utils.file_downloader.url_map[
            r"(.+)://aip.scitation.org/doi/([^/]+)"
        ] = r"1://aip.scitation.org/doi/pdf/2"
        config.utils.file_downloader.url_map[
            r"(.+)://quantum-journal.org/papers/([^/]+)"
        ] = r"1://quantum-journal.org/papers/2/pdf/" Make sure to use raw Python strings to ensure proper backslash-escaping.

config.utils.journal_abbreviations=[]
    You can specify a list of journal abbreviations. This list should be formatted as tuples of the form: (full journal name, abbreviation). The abbreviation should include any necessary punctuation which can be excluded upon export (see also cobib export --help).

EVENTS

Since v3.3.0 coBib comes with a number of subscribable events. Their
    configuration is detailed in the online documentation, https://cobib.gitlab.io/cobib/cobib/config/event.html, and will not be repeated here.

SHELL UTILITIES
In addition to the SUBCOMMANDS coBib also provides some "meta"-commands for varying purposes.

cobib _example_config
    Prints the example configuration. You can do the following to get started with a custom configuration:
        cobib _example_config > ~/.config/cobib/config.py

cobib _lint_database
    Lints the database file for potential points of formatting improvements.

-f, --format
If you provide this option, coBib will automatically format your database to resolve all found lint messages.

cobib _list_commands
    Lists all available SUBCOMMANDS.

cobib _list_labels
    Lists all labels in your database.

cobib _list_filters
    Lists all available filters.

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/cobib/cobib