Command line clients

From refbase

(Difference between revisions)
Revision as of 10:10, 14 June 2006
Matthias (Talk | contribs)
added 'recent refbase version' as a requirement (doh!)
← Previous diff
Revision as of 21:36, 3 October 2006
Matthias (Talk | contribs)
Command line client moved to Command line clients
Next diff →

Revision as of 21:36, 3 October 2006

This page documents the refbase command line client.


refbase command line client

refbase >v0.8.0 comes with a command line client written in Perl which allows you to search a refbase online database from the command line and retrieve results in various formats. By default, found results are returned as citations in plain text format, but search results can easily be saved as HTML, RTF, PDF, LaTeX or structured text (Markdown). In addition, found results can be exported to BibTeX, Endnote, RIS or XML (MODS, SRW, formats.

Besides using the refbase CLI to perform a quick database query from the shell, the command line client allows for easy integration of a refbase database into a custom workflow. Possible applications could be automatic backups via scheduled cron jobs or automatic creation and update of static publication lists that employ a custom HTML layout.


The refbase command line client requires:


  • Install required Perl modules (if missing)
Info about installing Perl modules from CPAN is available here and here. Here's a quick guide: you can check if the above mentioned CPAN modules are already installed on your system using these two commands from your shell:
perl -MLWP::Simple -e 1
perl -MURI::URL -e 1
If these commands don't return any error messages, you have the required modules. If you do see some error messages, it's still possible that these modules are installed on your system, but that they are not in your path, which can be displayed with:
perl -e "print qq(@INC)"
If the required CPAN modules are not installed on your system, you should be able to install them using the following commands:
perl -MCPAN -e 'install LWP::Simple'
perl -MCPAN -e 'install URI::URL'
The installation process will try to take care of any dependencies. However, if your module installation fails because of other missing modules, checkout the error messages and try to install the mentioned modules first, then try again to install LWP::Simple and URI::URL.
  • Download refbase CLI
Download the latest script version of the refbase command line client from the SourceForge CVS as source text.
  • Copy refbase CLI to executable path
Put the downloaded script file within an executable path and make sure that the file itself is executable.

You should now be able to type refbase at the command line to invoke the refbase command line client. See below for more info about the required syntax.


For help with the syntax type:

refbase -h
refbase --help

This will print the usage screen:

refbase command line client, v1.0 by Matthias Steffens,

Usage:   refbase [OPTIONS]

Notes:   - At least one query option must be given and unrecognized options will be ignored.
         - If multiple options are given, they will by default be connected with 'AND'. Use
           '--query=or' to connect multiple options with 'OR'.
         - Options syntax: [OPTION]=[VALUE], e.g. '-a=steffens' or '--author="steffens, m"'.
         - Returns up to '--rows' number of records beginning with '--start'. If all given
           query options are empty, all database records will be returned.
         - Note that '--records' assumes a list of full record serials separated by non-digit
           characters while '--serial' allows for partial matches.
         - For each option, default values can be specified at the top of the script.
           Current defaults are given in parentheses.

General Options:   -h, --help        - display this help text
                   -v, --version     - display version information
                   -X, --examples    - display usage examples

Query Options:     -a, --author      - search author field (' ')
                   -b, --abstract    - search abstract field (' ')
                   -c, --citekey     - search cite_key field, requires '-u, --userid' (' ')
                   -d, --date        - search by creation date (' ')
                   -e, --area        - search area field (' ')
                   -f, --thesis      - search thesis field (' ')
                   -i, --contribid   - search contribution_id field (' ')
                   -j, --journal     - search abbrev_journal field (' ')
                   -k, --keywords    - search keywords field (' ')
                   -l, --location    - search location field (' ')
                   -m, --marked      - search marked field, requires '-u, --userid' (' ')
                   -n, --notes       - search notes field (' ')
                   -p, --publication - search publication field (' ')
                   -q, --query       - query type, possible values: and, or ('and')
                   -r, --records     - search serial field (' ')
                   -s, --selected    - search selected field, requires '-u, --userid' (' ')
                   -t, --title       - search title field (' ')
                   -u, --userid      - join with user-specific data from user ID (' ')
                   -w, --where       - search by using a raw sql where clause (' ')
                   -x, --type        - search type field (' ')
                   -y, --year        - search year field (' ')
                   -z, --serial      - search serial field (partial matches) ('.+')

Output Options:    -C, --style       - citation style (' ')
                   -F, --format      - output format ('ascii')
                                       possible values: html, rtf, pdf, latex, markdown, ascii,
                                                        bibtex, endnote, ris, mods, srw, odf
                   -H, --host        - URL of the refbase database ('')
                   -L, --showlinks   - hide/display links column in html output ('1')
                                       possible values: 0, 1
                   -O, --order       - sort order of returned records ('author')
                                       possible values: author, year, type, type-year
                   -Q, --showquery   - hide/display SQL query in ASCII output ('0')
                                       possible values: 0, 1
                   -R, --rows        - number of records to be returned (' ')
                   -S, --start       - number of first record to be returned ('1')
                   -V, --view        - view type of html output ('web')
                                       possible values: web, print


To view some usage examples type:

refbase -X
refbase --examples

This will print the examples screen:


1) Find all records where the author field contains 'mock' AND the year field
   contains '2005':

   refbase -a=mock -y=2005


2) Find all records where the author field contains 'mock' OR the title field
   contains 'photo', and display 10 records starting with the 21st record in the
   result set:

   refbase -a=mock -t=photo -q=or -R=10 -S=21


3) Export records with serial numbers '1', '12' and '34' to Endnote format and
   save them to a file named 'export.enw':

   refbase -r=1,12,34 -F=endnote > export.enw


4) Return up to 50 records that were selected by a user with a user ID '2' in
   RTF format using citation style "Ann Glaciol" and sorting them first by
   record type, then by year, and save results to a file named 'citations.rtf':

   refbase -s=yes -u=2 -R=50 -F=rtf -C="Ann Glaciol" -O=type-year > citations.rtf


5) Find all records which were modified today by a user named "admin" and where
   the location field contains 'msteffens' (note the use of the '-w' option to
   specify a custom WHERE clause):

   refbase -w='modified_date = CURDATE() AND modified_by RLIKE "admin"' -l=msteffens


Current limitations

  • Currently, this utility supports search & retrieve, but does not support update actions such as add, edit or delete.
  • This script is currently just an interface to show.php, which for example does not support arbitrary sort orders.
  • User authentication has not been implemented. This means that, except for querying the user-specific fields cite_key, marked and selected, this script cannot access other user-specific information or display user-specific cite keys.
  • Specifying the record offset (--start) as well as the number of records to be returned (--rows) will only work for the formats html, rtf, pdf, latex, markdown, ascii and srw, since the other formats are designed to always export the entire result set. Note that for html, --start is adjusted to the next lower value that is an exact multiple of --rows (which ensures correct behaviour of the browse links).