Quick guide
In this quick guide, we’ll create a library, download a couple documents, and
then work on them by opening, tagging, updating, exporting, and organising them.
In doing so, you will be introduced to the papis
command and number of its
subcommands. These subcommands (which we’ll simply call “commands” from now on)
are run with papis COMMAND
(where COMMAND
is the command you want). To
get a list of all commands, simply run papis --help
. If you want to get help
with a specific command, check out papis COMMAND --help
.
Creating a new library
You can’t manage a library without a library to manage, and so the first thing we will do is create one! You could do this manually by editing the configuration file, but there’s a command that will help you get going:
papis init
This command will prompt you for some settings, such as the name and location of the library, which programs to use to open files, and so on. All of the settings can be changed by editing the configuration file, so feel free to accept the defaults for the time being and fine-tune them once you have become familiar with Papis.
Adding the first documents
Let’s populate our library next. There are several ways to add a document to
your library: you can automatically fetch a document’s metadata along with a PDF
or add the document manually. Adding documents is done with the papis add
command.
Let’s start with the automatic method. We will download an example article from arXiv: https://arxiv.org/abs/2404.14339. The command will download all the data, show the downloaded file, and then (after asking for confirmation) automatically add it to the library:
papis add --from arxiv https://arxiv.org/abs/2404.14339
We have invoked papis add
with the --from arxiv
option, which specifies
the arxiv
importer. Papis contains various importers, which allow it to
get data from a variety of online sources. Finally, we provide the arXiv URL of
the document in which we’re interested. You can take a look at all the other
available importers with papis list --importers
.
If Papis is missing an importer for some website, you may need to manually download the PDF and enter the metadata yourself. We’ll illustrate this by downloading the PDF of Isaac Newton’s Principia Mathematica and then adding the file along with some basic metadata:
curl https://www.gutenberg.org/files/28233/28233-pdf.pdf -o principia.pdf
papis add principia.pdf \
--set author "Isaac Newton" \
--set title "Principia Mathematica"
First, we download the file with curl
. We then run papis add
with the
filename as the first argument and two instances of the --set
option to
manually set the author
and title
(the papis add
command is split
over multiple lines with \
just so it displays better in this guide).
Finally, a situation that is unfortunately familiar to most: papers behind
paywalls. The importer might be able to get the metadata automatically but fail
at fetching the PDF. In this case, you might have to get the file yourself. You
can use a slightly modified papis add
command if you then want to create an
entry in your library.
curl https://www.unicode.org/L2/L2017/17407-frowning-poo.pdf -o poop.pdf
papis add poop.pdf --from doi https://doi.org/10.1007/s11192-017-2554-0
First, we’re downloading a PDF about the Unicode frowning poop emoji as
a substitute for the paywalled paper that you’d have downloaded yourself. We
then use papis add
with the doi
importer, which downloads metadata based
on an article’s doi
identifier (from Crossref).
Adding files
You can also add files to existing documents in your library. This can be useful in various situations. For instance, you might have tried to add a document, but Papis couldn’t download the relevant file. You then find the file elsewhere and want to add it to the existing document. Or maybe you’d like to add both the PDF and EPUB version of some file to a document. Just to show how this works, let’s add the frowning poop emoji PDF once more to the same document (so that we end up with two PDFs attached to it):
papis addto --files poop.pdf mikki
The path specified after --files
tells Papis where to find the file. Papis
will attach the file to the document that matches the query “mikki” or open the
picker if there are multiple matching documents.
Listing documents
All the documents you add end up in folders inside your library. To find out
where exactly a specific file is, use the papis list
command.
papis list
Here, Papis will open the picker listing all the files in the library. You can
further narrow down the results by typing your query. Alternatively, you can use
the arrow keys to select the entry you’re interested in. You can also use
ctrl-t
to select multiple entries. Pressing Enter
will leave the picker
and print the paths to the selected documents.
As usual, you can optionally provide a query to filter the database:
papis list newton
Here, Papis will list only the documents whose metadata matches “newton”. Because there is only one such document, Papis skips the picker and directly provides you with the path.
If you want to filter in a more specific manner, for instance by a document’s title, you can use the following:
papis list title:principia
Instead of by “title”, you can filter by any other field stored in the Papis library. The info.yaml section gives an overview of these fields.
Opening documents
Using papis list
to find a document’s path to manually open a file gets old
quickly. That’s why Papis also provides facilities to open documents directly.
We can open a document with:
papis open
This will work similarly to papis list
. If there are multiple matches, Papis
opens the picker, and if there is only a single match, the picker is skipped.
However, unlike papis list
, papis open
doesn’t print the path to the
document, but opens the attached file.
You can narrow down your query just as in papis list
:
papis open newton
Adding notes
You opened the Principia Mathematica and started reading. Now you want to jot down some notes so that you can review them later. Papis has built-in functionality for this:
papis edit --notes newton
We called papis edit
with the --notes
flag, which tells Papis that we
want to edit the note file (or create one if it doesn’t yet exist). We need to
specify --notes
because papis edit
will otherwise open the info.yaml where Papis stores the document’s metadata. The command ends
with the query “newton”, which we use to select the document in which we’re
interested.
Tagging the documents
As your library grows, you might want to add tags to keep things organised and searchable. For instance, you could create tags with your documents’ keywords, note whether you’ve read the document, keep track of publishing status, and so on.
Let’s say you want to add the tag “physics” to all documents by Isaac Newton:
papis tag --append physics newton
Or maybe, you want to tag the documents used in a specific project. We could add the tag “project apple” to them using the command
papis tag --append "project apple" newton
Because our tag has white space in it, we had to surround it with "
.
Updating documents
You realise that you want to adjust the metadata of the Principia Mathematica
document in our library. While “Isaac Newton” is indeed the guy’s name, you’d
like to be more polite and include his title and rename the author to “Sir Isaac
Newton”. While the papis tag
command we’ve discussed previously is
specialised for editing tags, the papis update
command can be used to change
metadata more generally. We can use it to easily rename the author:
papis update --set author "Sir Isaac Newton" newton
The structure of the command might be familiar to you by now. First, we use
--set author "Sir Isaac Newton"
to tell papis update
to set the author
to what we want, and then we add a query to identify the document we’re
interested in.
Exporting documents
You’re likely using some other piece of software to write text with proper referencing and bibliographies. The most widely supported file format used for these purposes is BibTeX. You can export your Papis library to BibTeX, so that you can then use it elsewhere.
To export all documents in the library to a BibTeX file called all.bib
, you
can use the command:
papis export --all --output all.bib
Note the use of the --all
flag. This tells Papis that you want to run the
command with all files that match the query. In this case, it means that papis
export
creates a .bib
file based on all documents in the library. Without
the --all
flag, Papis would instead have opened the picker (as it did in
previous examples where we didn’t use this flag), allowing you to select the
document.
To export only a part of the library, for instance all documents that contain the tag “project”, you can add a query:
papis export --all --output project_apple.bib tags:"project apple"
Papis supports exporting to several formats, which you can check out using
papis list --exporters
Renaming folders
Papis will automatically name the folders in your library in a reasonable (and
configurable) way, but if you want to rename them manually, you’re free to do
so. For this purpose, Papis offers the rename
command, which changes the
name of a document’s folder.
This can be particularly useful when you’ve adjusted some document’s metadata
and would like the folder’s name to reflect this. Remember how we changed the
author of the Principia Mathematica from “Isaac Newton” to “Sir Isaac Newton”?
Let’s make that show up in the folder name! It’s simple to do this: run papis
rename
, pick the relevant document, and follow the prompts. Here, you do not
need to set anything by hand as Papis regenerates the folder name based on the
updated metadata.
Alternatively, you could also use the --folder-name
option to set the folder
name to whatever you want. Finally, you could also adjust the
add-folder-name
configuration option so that folders are
automatically named according to your preferences.
Starting over
You should now know about Papis’ basics and be able to use it to organise your
library. If you want to start over and add your own documents, you may want to
delete the files we’ve added in this quick guide. You will need to delete the
Papis configuration folder and the library you’ve created when running papis
init
. This resets everything, so that by running papis init
again, you’ll
start anew.
If you’re unsure about the location of the library we’ve created for this quick guide, run the following command.
papis config --section papis dir
The papis config
command can tell you about the state of the Papis
configuration. Here, we’re asking it to give us the value of the option dir
in the section papis
. If you’ve changed the name of the library when running
papis init
you will need to change the section name to your library’s name.
You can now use rm -r
or your file browser to delete this folder.
The Papis configuration folder’s location depends on your operating system. You can find out where it is by running:
papis list --paths
The folder you’ll need to the delete is the one called PAPIS_CONFIG_FOLDER
.