Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install autobib

It will make the autobib command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall autobib uninstalls.

Back to the crate overview.

Readme

Autobib

Warning

Autobib is beta software.

Things might be broken.
Your data might be deleted.
The interface may change between releases.

On the other hand, core functionality of Autobib is currently quite stable (and under regular use by the authors). If you use this software, please:

Keep regular backups of the $XDG_DATA_HOME/autobib directory, which contains the key user files which may be modified by this program.
Follow updates by reading the changelog files.
Report any issues in the issues page.

Autobib is a command-line tool for managing bibliographic records. Unlike other bibliography management tools such as Zotero or JabRef, Autobib aims to be a lower-level tool for providing an interface between local records, remote records, and bibliographic records associated with a project.

Moreover, Autobib is designed with first-class support for BibTeX.

Installation

Pre-compiled binaries for recent tagged releases can be found on the releases page.

If you use Homebrew, then you can also install Autobib through our tap:

brew tap autobib/autobib
brew install autobib

If a binary is not available for your platform, you can install from source. Make sure the rust toolchain is installed on your device and run

cargo install --locked autobib

Basic usage

To see all the commands available with Autobib, run

autobib help
autobib help <subcommand>

Jump to:

Getting records

At its most basic, Autobib converts identifiers into records. To obtain the data associated with the zbMath record Zbl 1337.28015, running

autobib get zbl:1337.28015

will return

@article{zbl:1337.28015,
  author = {Hochman, Michael},
  doi = {10.4007/annals.2014.180.2.7},
  journal = {Ann. Math. (2)},
  language = {English},
  pages = {773--822},
  title = {On self-similar sets with overlaps and inverse theorems for entropy},
  volume = {180},
  year = {2014},
  zbl = {1337.28015},
  zbmath = {06346461},
}

An identifier is a pair provider:sub_id. The currently supported providers are:

arxiv: An arXiv identifier, such as arxiv:1212.1873 or arxiv:math/9201254
doi: A DOI identifier, such as doi:10.4007/annals.2014.180.2.7
isbn: An ISBN, either 10 or 13 digits, such as isbn:9781119942399.
jfm: A special zbMath identifier mainly for old records, such as jfm:60.0017.02
ol: An Open Library book edition, such as ol:31159704M
mr: A MathSciNet identifier, such as mr:3224722
zbl: A zbMath external identifier of the form xxxx.xxxxx, such as zbl:1337.28015
zbmath: A zbMath internal identifier of the form xxxxxxxx, such as zbmath:06346461

If your preferred format is not supported, feel free to open an issue on the GitHub repository!

Sourcing from files

A more common scenario is that you have a file, say main.tex, with some contents:

% contents of file `main.tex`
\documentclass{article}
\begin{document}
We refer the reader to \cite{zbl:1337.28015,zbl:1409.11054}.
\end{document}

Then, for example, running

autobib source main.tex --out main.bib

will search through the document for valid citation keys and output the bibliography into the file main.bib.

Modifying records

On the first run, Autobib retrieves the data directly from a remote provider. The data is stored locally in a SQLite database, so that subsequent runs are substantially faster.

You can view and modify the internally stored record with

autobib edit zbl:1337.28015

If the record does not yet exist in your local record database, it will be retrieved before editing. Autobib also supports non-interactive edit commands: run autobib help edit for more detail.

You can also:

remove a record from the database using the autobib delete command,
merge an existing record into another (perhaps automatically determined) one using the autobib replace command, and
re-retrieve a record from the remote provider using the autobib update command.

Run autobib help (delete|replace|update).

The modifications performed by edits, deletions, replacements, and updates (except when using the special --hard flag) are always recoverable. See the edit history section for more detail.

Assigning aliases

It is also possible to assign aliases to records, using the autobib alias sub-command. To create an alias for the record with identifier zbl:1337.28015, run

autobib alias add hochman-entropy zbl:1337.28015

Then running autobib get hochman-entropy returns

@article{hochman-entropy,
  author = {Hochman, Michael},
  doi = {10.4007/annals.2014.180.2.7},
  journal = {Ann. Math. (2)},
  language = {English},
  pages = {773--822},
  title = {On self-similar sets with overlaps and inverse theorems for entropy},
  volume = {180},
  year = {2014},
  zbl = {1337.28015},
  zbmath = {06346461},
}

The record is identical to the record zbl:1337.28015, except that the citation key is the name of the alias. In order to distinguish from usual identifiers, an alias cannot contain the colon :.

Note that the characters {}(),=\#%" and whitespace are not permitted in a BibTeX entry key. You can still create aliases using these characters: for instance, autobib alias add % zbl:1337.28015 works. However, attempting to retrieve the BibTeX entry associated with this alias will result in an error.

$ autobib get %
error: Invalid bibtex entry key: %
suggestion: use an alias which does not contain disallowed characters: {}(),=\#%"

Run autobib help alias for more options for managing aliases.

Aliases can be used in most locations that the usual identifiers are used. For instance, you can run autobib edit hochman-entropy, to edit the corresponding record data. Note that these edits will apply to the original underlying record.

See the data model documentation for more precise information on how Autobib uses identifiers.

Many providers have default key formats; for instance, zbMath internally uses keys of the form zbMATH06346461. Autobib can be configured to automatically convert aliases matching certain rules to provider:sub_id pairs. For example, to convert zbMATH06346461 to zbmath:06346461 and automatically generate permanent aliases in your database, use the [alias_transform] section in your configuration:

[alias_transform]
rules = [["^zbMATH([0-9]{8})$", "zbmath"]]
create_alias = true

Read the default configuration for more detail.

Creating local records

Sometimes, it is necessary to create a local record which may not otherwise exist on a remote database. In order to do this, the command autobib local can be used to generate a special local: record, which only exists locally in the database. For example,

autobib local my-entry

creates a record under the identifier local:my-entry. You will be prompted to fill in data for the record. To modify the record later, run the above command again or use the autobib edit command.

It is also possible to create the local record from a BibTeX file:

autobib local my-entry --from-bibtex source.bib

Note that the BibTeX file should contain exactly one entry, or this command will fail.

Searching for records

In order to search for records which are saved on your local database, use the autobib find command. This will open a fuzzy picker for searching through various fields. You can customize the search syntax using templates. For example,

autobib find -t '{author}: {title}'

will list all of your local records with the author and title fields available to search against.

Read more in the template syntax documentation.

Working with edit history

Autobib maintains a comprehensive edit history: every change to a record in the database creates a new copy with the changes, and the old copy is saved in the database.

You can recover the previous version(s) using autobib hist undo and autobib hist redo.

Internally, undo-states are stored as a tree: you can visualize the entire edit history associated with an identifier using autobib log --tree. You can move to arbitrary states in the edit tree using autobib hist reset.

Your data is never deleted automatically. See autobib hist prune for a variety of commands which can be used to delete unwanted revisions.

See the data model documentation for more information.

Importing records

You can import existing records from BibTeX files using autobib import.

Autobib automatically determines identifiers from the import data. To pick an identifier, Autobib first uses the preferred_providers section in your configuration, or falls back to whatever identifier it can find. Usually this is what you want: for example, if your data contains a doi = {...} field and preferred_providers = ["doi"] this will always be used as the identifier. Note that the [alias_transform] section of the configuration also applies. This can be used to define a custom import pattern to map the citation keys to identifiers, if your citation keys are in a special format.

If you are importing data with an identifier format that Autobib does not recognize, the --local-fallback option creates special local:... identifiers using the citation keys in the BibTeX file.

Autobib tries to make imports as fine-grained as possible. Even if one entry fails to import, it will continue to try to import the remaining entries. Any entry which could not be imported is printed to standard output along with a short description (in a BibTeX comment) explaining why the file could not be imported. This means you can use a workflow like the following:

# make sure to use a different output filename here, or the redirection will erase
# the file before Autobib can read it
autobib import file.bib > failed.bib

# modify the failed entries to fix the issues
vim failed.bib

# try again
autobib import failed.bib > failed_again.bib

You can also import attachments using the --include-files flag. See the attachments for more detail when working with attachments.

Managing attachments

Autobib has basic support for working with attachments.

Autobib subscribes to the philosophy that your file-system is the best tool for manipulating attachments. Instead of trying to replicate features of your file-system, Autobib instead looks for files at a specific, consistently-defined location.

The attachment directory depends only on the canonical identifier associated with the record and can be obtained with the autobib path subcommand:

# by default, prints '~/.local/share/autobib/attachments/zbmath/JX/TT/CT/GA3DGNBWGQ3DC===/'
autobib path zbl:1337.28015

To manage attachments, simply browse to the relevant attachment directory and manage the files in your preferred way. As a convenience method, you can attach new files with

autobib attach <ident> <file>

This will copy the file into the attachment directory. Use the --rename option to specify a new filename.

You can also browse attachments using autobib find --mode attachments. This will open an interactive browser of all records in your database which contain files. Upon selecting a record, if there are multiple files, you will be further prompted to select one from those files. The resulting filename will be printed.

This means searching for a file by metadata and opening it is as simple as running

open "$(autobib find --mode attachments)"

replacing open with the correct command on your system to open the file with the correct application.

Shell completions

Autobib supports shell completion of commands and options in shells like Bash and Zsh. See supported shells.

Note

If you installed Autobib via Homebrew and are using Zsh, Bash, or Fish, then the completions script is already available inside the Homebrew prefix. Follow the instructions here to have your shell load the Homebrew-managed completions.

A shell completions script can be generated as follows:

autobib completions <shell>

Run this on interactive shell start-up and redirect the output to your preferred directory of completions scripts.

For example, in Zsh, add the following lines to ~/.zshrc:

if type autobib &> /dev/null
then
  autobib completions zsh > "$HOME/.local/share/zsh/site-functions/_autobib"
fi

and make sure ~/.local/share/zsh/site-functions (or another directory of your choice) is added to the FPATH environment variable.

In Bash, add the following lines to ~/.profile:

if type autobib &> /dev/null
then
  autobib completions bash > "$HOME/.local/share/bash-completion/completions/autobib"
fi

For this to take effect, remember to restart your shell or source the relevant file. Then you can try typing autobib f and pressing the tab key. You should see autobib find .

User data and configuration file

Autobib's SQLite database is by default kept at $XDG_DATA_HOME/autobib/records.db, or ~/.local/share/autobib/records.db if $XDG_DATA_HOME is not set or empty. This path can be modified with the AUTOBIB_DATABASE_PATH environment variable.

Autobib stores file attachments in subfolders of $XDG_DATA_HOME/autobib/attachments, or ~/.local/share/autobib/attachments if $XDG_DATA_HOME is not set or empty. This path can be modified with the AUTOBIB_ATTACHMENTS_DIRECTORY environment variable.

Autobib supports basic global configuration through a TOML file which defaults to $XDG_CONFIG_HOME/autobib/config.toml, or $HOME/.config/autobib/config.toml if $XDG_CONFIG_HOME is not set or empty. This path can be modified with the AUTOBIB_CONFIG_PATH environment variable. You can generate a default configuration file with autobib default-config, or view the configuration options here.

License

The source code of Autobib is distributed under the terms of the GNU Affero General Public License, version 3 (or any later version).