Commands

Add

The add command is one of the central commands of the papis command line interface. It is a very versatile command with a fair amount of options.

There are also customization settings availabe for this command, check out the configuration page for add.

Examples

  • Add a document located in ~/Documents/interesting.pdf and name the folder where it will be stored in the database interesting-paper-2021

    papis add ~/Documents/interesting.pdf \
        --folder-name interesting-paper-2021
    

    if you want to add directly some key values, like author, title and tags, you can also run the following:

    papis add ~/Documents/interesting.pdf \
        --folder-name interesting-paper-2021 \
        --set author 'John Smith' \
        --set title 'The interesting life of bees' \
        --set year 1985 \
        --set tags 'biology interesting bees'
    
  • Add a paper that you have locally in a file and get the paper information through its doi identifier (in this case 10.10763/1.3237134 as an example):

    papis add ~/Documents/interesting.pdf --from doi 10.10763/1.3237134
    
  • Add paper to a library named machine-learning from arxiv.org

    papis -l machine-learning add \
        --from url https://arxiv.org/abs/1712.03134
    
  • If you do not want copy the original pdfs into the library, you can also tell papis to just create a link to them, for example

    papis add --link ~/Documents/interesting.pdf \
        --from doi 10.10763/1.3237134
    

    will add an entry into the papis library, but the pdf document will remain at ~/Documents/interesting.pdf, and in the document’s folder there will be a link to ~/Documents/interesting.pdf instead of the file itself. Of course you always have to be sure that the document at ~/Documents/interesting.pdf does not disappear, otherwise you will end up without a document to open.

  • Papis also tries to make sense of the inputs that you have passed to the command, for instance you could provide only a doi and papis will try to know if this is indeed a doi

    papis add 10.1103/PhysRevLett.123.156401
    

    or from a url

    papis add https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.123.156401
    

Examples in python

There is a python function in the add module that can be used to interact in a more effective way in python scripts,

papis.commands.add.run(paths, data={}, folder_name=None, file_name=None, subfolder=None, confirm=False, open_file=False, edit=False, git=False, link=False)[source]
Parameters
  • paths ([]) – Paths to the documents to be added

  • data (dict) – Data for the document to be added. If more data is to be retrieved from other sources, the data dictionary will be updated from these sources.

  • folder_name (str) – Name of the folder where the document will be stored

  • file_name (str) – File name of the document’s files to be stored.

  • subfolder (str) – Folder within the library where the document’s folder should be stored.

  • confirm (bool) – Wether or not to ask user for confirmation before adding.

  • open_file (bool) – Wether or not to ask user for opening file before adding.

  • edit (bool) – Wether or not to ask user for editing the infor file before adding.

  • git (bool) – Wether or not to ask user for committing before adding, in the case of course that the library is a git repository.

Cli

papis add

Add a document into a given library

papis add [OPTIONS] [FILES]...

Options

-h, --help

Show this message and exit.

-s, --set <set_list>

Set some information before

-d, --subfolder <subfolder>

Subfolder in the library

--folder-name <folder_name>

Name for the document’s folder (papis format)

--file-name <file_name>

File name for the document (papis format)

--from <from_importer>

Add document from a specific importer (bibtex, folder, pmid, pdf2doi, crossref, arxiv, yaml, pdf2arxivid, doi, lib)

-b, --batch

Batch mode, do not prompt or otherwise

--confirm, --no-confirm

Ask to confirm before adding to the collection

--open, --no-open

Open file before adding document

--edit, --no-edit

Edit info file before adding document

Instead of copying the file to the library, create a link toits original location

--git, --no-git

Git add and commit the new document

--list-importers, --li

List all available papis importers

Arguments

FILES

Optional argument(s)

Addto

This command adds files to existing papis documents in some library.

For instance imagine you have two pdf files, a.pdf and b.pdf that you want to add to a document that matches with the query string einstein photon definition, then you would use

papis addto 'einstein photon definition' -f a.pdf -f b.pdf

notice that we repeat two times the flag -f, this is important.

Cli

papis addto

Add files to an existing document

papis addto [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Add and commit files

-f, --files <files>

File fullpaths to documents

--file-name <file_name>

File name for the document (papis format)

Arguments

QUERY

Optional argument

Browse

This command will try its best to find a source in the internet for the document at hand.

Of course if the document has an url key in its info file, it will use this url to open it in a browser. Also if it has a doc_url key, or a doi, it will try to compose urls out of these to open it.

If none of the above work, then it will try to use a search engine with the document’s information (using the browse-query-format). You can select wich search engine you want to use using the search-engine setting.

Cli

papis browse

Open document’s url in a browser

papis browse [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

-k, --key <key>

Use the value of the document’s key to open in the browser, e.g.doi, url, doc_url …

--all

Browse all selected documents

Arguments

QUERY

Optional argument

Bibtex

This command helps to interact with bib files in your LaTeX projects.

Examples

papis bibtex                                  read new_papers.bib                   \ # Read bib file
  cmd 'papis add --from-doi {doc[doi]}'   # For every entry run the command

I use it for opening some papers for instance

papis bibtex read new_papers.bib open

or to add papers to the bib

papis bibtex                read new_papers.bib \ # Read bib file
  add einstein        \ # Pick a document with query 'einstein' from library
  add heisenberg      \ # Pick a document with query 'heisenberg' from library
  save new_papers.bib   # Save in new_papers.bib

or if I update some information in my papis yaml files then I can do

papis bibtex                read new_papers.bib \ # Read bib file
  update -f           \ # Update what has been read from papis library
  save new_papers.bib   # save everything to new_papers.bib, overwriting

Maybe this is also interesting for you guys!

Vim integration

Right now, you can easily use it from vim with these simple lines

function! PapisBibtexRef()
  let l:temp = tempname()
  echom l:temp
  silent exec "!papis bibtex ref -o ".l:temp
  let l:olda = @a
  let @a = join(readfile(l:temp), ',')
  normal! "ap
  redraw!
  let @a = l:olda
endfunction

command! -nargs=0 BibRef call PapisBibtexRef()
command! -nargs=0 BibOpen exec "!papis bibtex open"

And use like such: asciicast

Cli

papis add

Add a document into a given library

papis add [OPTIONS] [FILES]...

Options

-h, --help

Show this message and exit.

-s, --set <set_list>

Set some information before

-d, --subfolder <subfolder>

Subfolder in the library

--folder-name <folder_name>

Name for the document’s folder (papis format)

--file-name <file_name>

File name for the document (papis format)

--from <from_importer>

Add document from a specific importer (bibtex, folder, pmid, pdf2doi, crossref, arxiv, yaml, pdf2arxivid, doi, lib)

-b, --batch

Batch mode, do not prompt or otherwise

--confirm, --no-confirm

Ask to confirm before adding to the collection

--open, --no-open

Open file before adding document

--edit, --no-edit

Edit info file before adding document

Instead of copying the file to the library, create a link toits original location

--git, --no-git

Git add and commit the new document

--list-importers, --li

List all available papis importers

Arguments

FILES

Optional argument(s)

Config

The command config is a useful command because it allows you to check the configuration settings’ values that your current papis session is using.

For example let’s say that you want to see which dir setting your current library is using (i.e., the directory or the dir that appears in the definition of the library in the configuration file), then you would simply do:

papis config dir

If you wanted to see which dir the library books has, for example then you would do

papis -l books config dir

This works as well for default settings, i.e., settings that you have not customized, for example the setting match-format, you would check it with

papis config match-format
> {doc[tags]}{doc.subfolder}{doc[title]}{doc[author]}{doc[year]}

You can find a list of all available settings in the configuration section.

Cli

papis config

Print configuration values

papis config [OPTIONS] OPTION

Options

-h, --help

Show this message and exit.

Arguments

OPTION

Required argument

Main

Examples

  • To override some configuration options, you can use the flag --set, for instance, if you want to override the editor used and the opentool to open documents, you can just type

    papis --set editor gedit --set opentool firefox edit
    papis --set editor gedit --set opentool firefox open
    
  • If you want to list the libraries and pick one before sending a database query to papis, use --pick-lib as such

    papis --pick-lib open 'einstein relativity'
    

Cli

papis

papis [OPTIONS] COMMAND [ARGS]...

Options

-h, --help

Show this message and exit.

--version

Show the version and exit.

-v, --verbose

Make the output verbose (equivalent to –log DEBUG)

-l, --lib <lib>

Choose a library name or library path (unamed library)

-c, --config <config>

Configuration file to use

--log <log>

Logging level

Options

INFO|DEBUG|WARNING|ERROR|CRITICAL

--pick-lib

Pick library to use

--cc, --clear-cache

Clear cache of the library used

-s, --set <set_list>

Set key value, e.g., –set info-name information.yaml –set opentool evince

--color <color>

Prevent the output from having color

Options

always|auto|no

Edit

This command edits the information of the documents. The editor used is defined by the editor configuration setting.

Cli

papis edit

Edit document information from a given library

papis edit [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--doc-folder <doc_folder>

Apply action to a document path

--git, --no-git

Add changes made to the info file

-n, --notes

Edit notes associated to the document

--all

Edit all matching documents

-e, --editor <editor>

Editor to be used

Arguments

QUERY

Optional argument

Explore

This command is in an experimental stage but it might be useful for many people.

Imagine you want to search for some papers online, but you don’t want to go into a browser and look for it. Explore gives you way to do this, using several services available online, more should be coming on the way.

An excellent such resource is crossref, which you can use by using the subcommand crossref:

papis explore crossref --author 'Freeman Dyson'

If you issue this command, you will see some text but basically nothing will happen. This is because explore is conceived in such a way as to concatenate commands, doing a simple

papis explore crossref -h

will tell you which commands are available. Let us suppose that you want to look for some documents on crossref, say some papers of Schroedinger, and you want to store them into a bibtex file called lib.bib, then you could concatenate the commands crossref and export --format bibtex as such

papis explore crossref -a 'Schrodinger' export --format bibtex lib.bib

This will store everything that you got from crossref in the file lib.bib and store in bibtex format. explore is much more flexible than that, you can also pick just one document to store, for instance let’s assume that you don’t want to store all retrieved documents but only one that you pick, the pick command will take care of it

papis explore crossref -a 'Schrodinger' pick export --format bibtex lib.bib

notice how the pick command is situated before the export. More generally you could write something like

papis explore \
    crossref -a Schroedinger \
    crossref -a Einstein \
    arxiv -a 'Felix Hummel' \
    export --format yaml docs.yaml \
    pick  \
    export --format bibtex specially-picked-document.bib

The upper command will look in crossref for documents authored by Schrodinger, then also by Einstein, and will look on the arxiv for papers authored by Felix Hummel. At the end, all these documents will be stored in the docs.yaml. After that we pick one document from them and store the information in the file specially-picked-document.bib, and we could go on and on.

If you want to follow-up on these documents and get them again to pick one, you could use the yaml command to read in document information from a yaml file, i.e., the previously created docs.yaml

papis explore \
    yaml docs.yaml \
    pick \
    cmd 'papis scihub {doc[doi]}' \
    cmd 'firefox {doc[url]}'

In this last example, we read the documents’ information from docs.yaml and pick a document, which then feed into the explore cmd command, that accepts a papis formatting string to issue a general shell command. In this case, the picked document gets fed into the papis scihub command which tries to download the document using scihub, and also this very document is tried to be opened by firefox (in case the document does have a url).

Cli

papis explore

Explore new documents using a variety of resources

papis explore [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

Options

-h, --help

Show this message and exit.

arxiv

Look for documents on ArXiV.org.

Examples of its usage are

papis explore arxiv -a ‘Hummel’ -m 100 arxiv -a ‘Garnet Chan’ pick

If you want to search for the exact author name ‘John Smith’, you should enclose it in extra quotes, as in the example below

papis explore arxiv -a ‘“John Smith”’ pick

papis explore arxiv [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
-a, --author <author>
-t, --title <title>
--abstract <abstract>
--comment <comment>
--journal <journal>
--report-number <report_number>
--category <category>
--id-list <id_list>
--page <page>
-m, --max <max>
base

Look for documents on the BielefeldAcademicSearchEngine

Examples of its usage are

papis explore base -q ‘Albert einstein’ pick cmd ‘firefox {doc[url]}’

papis explore base [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
bibtex

Import documents from a bibtex file

Examples of its usage are

papis explore bibtex lib.bib pick

papis explore bibtex [OPTIONS] BIBFILE

Options

-h, --help

Show this message and exit.

Arguments

BIBFILE

Required argument

citations

Query the citations of a paper

Example:

Go through the citations of a paper and export it in a yaml file

papis explore citations ‘einstein’ export –format yaml einstein.yaml

papis explore citations [OPTIONS] [QUERY]

Options

--doc-folder <doc_folder>

Apply action to a document path

-h, --help

Show this message and exit.

-s, --save

Store the citations in the document’s folder for later use

--rmfile

Remove the stored citations file

-m, --max-citations <max_citations>

Number of citations to be retrieved

Arguments

QUERY

Optional argument

cmd

Run a general command on the document list

Examples of its usage are:

Look for 200 Schroedinger papers, pick one, and add it via papis-scihub

papis explore crossref -m 200 -a ‘Schrodinger’

pick cmd ‘papis scihub {doc[doi]}’

papis explore cmd [OPTIONS] COMMAND

Options

-h, --help

Show this message and exit.

Arguments

COMMAND

Required argument

crossref

Look for documents on crossref.org.

Examples of its usage are

papis explore crossref -a ‘Albert einstein’ pick export –bibtex lib.bib

papis explore crossref [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>

General query

-a, --author <author>

Author of the query

-t, --title <title>

Title of the query

-m, --max <max>

Maximum number of results

-f, --filter <filter>

Filters to apply

-o, --order <order>

Order of appearance according to sorting [default: desc]

Options

asc|desc

-s, --sort <sort>

Sorting parameter [default: score]

Options

relevance|score|updated|deposited|indexed|published|published-print|published-online|issued|is-referenced-by-count|references-count

dissemin

Look for documents on dissem.in

Examples of its usage are

papis explore dissemin -q ‘Albert einstein’ pick cmd ‘firefox {doc[url]}’

papis explore dissemin [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
export

Export retrieved documents into various formats for later use

Examples of its usage are

papis explore crossref -m 200 -a ‘Schrodinger’ export –yaml lib.yaml

papis explore export [OPTIONS]

Options

-h, --help

Show this message and exit.

-f, --format <format>

Format for the document

Options

bibtex|yaml|json

-o, --out <out>

Outfile to write information to

isbn

Look for documents using isbnlib

Examples of its usage are

papis explore isbn -q ‘Albert einstein’ pick cmd ‘firefox {doc[url]}’

papis explore isbn [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
-s, --service <service>
Options

wcat|goob|openl

isbnplus

Look for documents on isbnplus.com

Examples of its usage are

papis explore isbnplus -q ‘Albert einstein’ pick cmd ‘firefox {doc[url]}’

papis explore isbnplus [OPTIONS]

Options

-h, --help

Show this message and exit.

-q, --query <query>
-a, --author <author>
-t, --title <title>
json

Import documents from a json file

Examples of its usage are

papis explore json lib.json pick

papis explore json [OPTIONS] JSONFILE

Options

-h, --help

Show this message and exit.

Arguments

JSONFILE

Required argument

lib

Query for documents in your library

Examples of its usage are

papis lib -l books einstein pick

papis explore lib [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--doc-folder <doc_folder>

Apply action to a document path

-l, --library <library>

Papis library to look

Arguments

QUERY

Optional argument

pick

Pick a document from the retrieved documents

Examples of its usage are

papis explore bibtex lib.bib pick

papis explore pick [OPTIONS]

Options

-h, --help

Show this message and exit.

-n, --number <number>

Pick automatically the n-th document

yaml

Import documents from a yaml file

Examples of its usage are

papis explore yaml lib.yaml pick

papis explore yaml [OPTIONS] YAMLFILE

Options

-h, --help

Show this message and exit.

Arguments

YAMLFILE

Required argument

Export

The export command is useful to work with other programs such as bibtex.

Some examples of its usage are:

  • Export one of the documents matching the author with einstein to bibtex:

papis export --format bibtex 'author : einstein'

or export all of them

papis export --format bibtex --all 'author : einstein'
  • Export all documents to bibtex and save them into a lib.bib file

papis export --all --format bibtex --out lib.bib
  • Export a folder of one of the documents matching the word krebs into a folder named, interesting-document

  papis export --folder --out interesting-document krebs

this will create the folder ``interesting-document`` containing the
``info.yaml`` file, the linked documents and a ``bibtex`` file for
sharing with other people.

Cli

papis export

Export a document from a given library

papis export [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--folder

Export document folder to share

-o, --out <out>

Outfile or outdir

-f, --format <format>

Format for the document

Options

bibtex|yaml|json

-a, --all

Export all without picking

Arguments

QUERY

Optional argument

Git

This command is useful if your library is itself a git repository. You can use this command to issue git commands in your library repository without having to change your current directory.

CLI Examples

  • Check the status of the library repository:

papis git status
  • Commit all changes:

papis git commit -a

List

This command is to list contents of a library.

CLI Examples

  • List all document files associated will all entries:

    papis list --all --file
    
  • List all document year and title with custom formatting:

    papis list --all --format '{doc[year]} {doc[title]}'
    
  • List all documents according to the bibitem formatting (stored in a template file bibitem.template):

    papis list --all --template bibitem.template
    

Cli

papis list

List documents’ properties

papis list [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

-i, --info

Show the info file name associated with the document

-f, --file

Show the file name associated with the document

-d, --dir

Show the folder name associated with the document

-n, --notes

List notes files, if any

--format <_format>

List entries using a custom papis format, e.g. ‘{doc[year] {doc[title]}

--template <template>

Template file containing a papis format to list entries

--downloaders

List available downloaders

--libraries

List defined libraries

-a, --all

Process all documents matching a query, if a query is given

Arguments

QUERY

Optional argument

Mv

Cli

papis mv

Move a document into some other path

papis mv [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Add git interoperability

Arguments

QUERY

Optional argument

Open

The open command is a very important command in the papis workflow. With it you can open documents, folders or marks.

Marks

One of special things about this command is the possibility of creating marks for documents. As you would imagine, it is in general difficult to create marks for any kind of data. For instance, if our library consists of pdf files and epub files for instance, we would like to define bookmarks in order to go back to them at some later point.

How you define marks can be customized through the marks configuration settings here. The default way of doing it is just by defining a marks list in a document. Let us look at a concrete example:

author: Isaiah Shavitt, Rodney J. Bartlett
edition: '1'
files: [book.pdf]
isbn: 052181832X,9780521818322

marks:
- {name: Intermediates definition, value: 344}
- {name: EOM equations, value: 455}

publisher: Cambridge University Press
ref: book:293288
series: Cambridge Molecular Science
title: 'Many-Body Methods in Chemistry and Physics'
type: book
year: '2009'

This book has defined two marks. Each mark has a name and a value. If you tell the open command to open marks, then it will look for the marks and open the value (page number). This is the default behaviour, however if you go to the configuration you’ll see that you can change the convention to what it suits you.

Examples

  • Open a pdf file linked to a document matching the string bohm

    papis open bohm
    
  • Open the folder where this last document is stored

    papis open -d bohm
    

    Please notice that the file browser used will be also related to the file-browser setting.

  • Open a mark defined in the info file

    papis open --mark bohm
    

Cli

papis open

Open document from a given library

papis open [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--doc-folder <doc_folder>

Apply action to a document path

--tool <tool>

Tool for opening the file (opentool)

-d, --dir

Open directory

--all

Open all matching documents

-m, --mark, --no-mark

Open mark

Arguments

QUERY

Optional argument

Rename

Cli

papis rename

Rename entry

papis rename [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Add git interoperability

Arguments

QUERY

Optional argument

Rm

Cli

papis rm

Delete a document or a file

papis rm [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Remove in git

--file

Remove files from a document instead of the whole folder

-f, --force

Do not confirm removal

--all

Remove all matches

Arguments

QUERY

Optional argument

Run

This command is useful to issue commands in the directory of your library.

CLI Examples

  • List files in your directory

papis run ls
  • Find a file in your directory using the find command

papis run find -name 'document.pdf'

Python examples

Cli

papis run

Run an arbitrary shell command in the library folder

papis run [OPTIONS] [RUN_COMMAND]...

Options

-h, --help

Show this message and exit.

Arguments

RUN_COMMAND

Optional argument(s)

Update

This command is to update the information of the documents. Some examples of the usage are given below

Examples

  • Update a document automatically and interactively (searching by doi number in crossref, or in other sources…)

    papis update --auto -i "author : dyson"
    
  • Update your library from a bib(la)tex file where many entries are listed. papis will try to look for documents in your library that match these entries and will ask you entry per entry to update it (of course this is done if you use the -i flag for interactively doing it). In the example libraryfile.bib is a file containing many entries.

    papis update --from bibtex libraryfile.bib -i
    
  • Tag all einstein papers with the tag classics

    papis update --all --set tags classics einstein
    

and add the tag of physics to all papers tagged as classics

papis update --all --set tags '{doc[tags]} physics' einstein

Cli

papis update

Update a document from a given library

papis update [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--git, --no-git

Add git interoperability

--doc-folder <doc_folder>

Apply action to a document path

--auto

Try to parse information from different sources

--all

Update all entries in library

--from <from_importer>

Add document from a specific importer (bibtex, folder, pmid, pdf2doi, crossref, arxiv, yaml, pdf2arxivid, doi, lib)

-s, --set <set_tuples>

Update document’s information with key value.The value can be a papis format.

Arguments

QUERY

Optional argument