A simple and minimal CLI tool to manage your references.
PicoRef is based on plain text: your library is just a folder, and each reference is a subfolder within that library. The metadata for each reference is stored in the CSL JSON format, but is encoded as yaml
to facilitate manual edits.
PicoRef's scope of functionality is deliberately small. It focuses on just a few things:
- Managing the files that make up your library (e.g. creating directories when needed, placing PDFs in the same subdirectory as the reference metadata, tags for managing collections)
- Adding new references to your library from a DOI using the CrossRef API and various APIs provided by preprint servers
- Fetching open access PDFs when available via preprint servers or UnPaywall
For more advanced functionality, I encourage you to compose PicoRef with other CLI tools like ripgrep
, fzf
, just
, and watchexec
. Otherwise, if you are looking for additional features there are also excellent alternatives like Papis, and Zotero.
- Make sure you have installed the rust toolchain
- Clone this repository and
cd
into it - Compile and install the binary:
cargo install --path .
- Create a configuration file (see below)
PicoRef will search for a configuration file in the following locations (in order of priority):
$XDG_CONFIG_HOME/picoref/config.toml
$HOME/.config/picoref/config.toml
The configuration file should contain two values:
root = "/absolute/path/to/your/library/folder"
email = "[email protected]"
(Email is used to access the polite pool of some APIs when fetching metadata or PDF files)
picoref add "<DOI>"
picoref pdf "<citekey>"
picoref export "path/to/export/json"
Use tags (see below)
- Choose a tag name for the project (e.g.
my-project
) - Apply that tag to all of the references associated with the project
- Filter your export using the tag:
picoref export "path/to/export/json" --tag 'my-project'
picoref tag add "<tag>" "<citekey>"
picoref list --tag "<tag>"
picoref tag list
Note: it is not yet possible to migrate attachments. The instructions below will only migrate your references themselves.
- Install the BetterBibTeX plugin for Zotero
- Open Zotero
- Right-click on
My Library
- Click on
Export Library...
- Choose the format:
Better CSL JSON
- Click OK
- Choose a path to export your JSON file
Then:
picoref import "path/to/your/file.json"
rm -r "$YOUR_LIBRARY/<citekey>"
- I wanted a very simple way to manage my references in plain text
- Papis looks great, but installing python apps with dependencies is a pain and I only need a small subset of its functionality
- I wanted to practice using Rust, and this seemed like a good project with a reasonably small scope