Command-line interface to openEQUELLA

Eric Phetteplace (@phette23), Systems Librarian, California College of the Arts Libraries

About CCA

Quick Background

equella-cli or eq is a set of command-line shortcuts written in node.js for HTTP requests to the REST API. It uses a configured .equellarc file with at least an OAuth token and "root" URL of an oE instance.

$ npm install --global equella-cli # installation

						// .equellarc
						  "root": "",
						  "token": "1234abcd-4321-dcba-1234abcd4321"

First, an example

This prints the title and URL of the first item contributed by the internal user "audrelorde".

						$ eq search --order=date --reverse --owner \
						> (eq user --name 'audrelorde' | jq -r .id) \
						> | jq '.results[0] | .name, .links.view'

Motivations behind eq

  • Learn more about openEQUELLA
  • Learn more about node.js & writing a CLI
  • I'm happy when I'm in my terminal

Text is the universal interface

Basics of the Unix Philosophy by Eric Steven Raymond.


  • Comprehensive, you can do almost anything
  • Already support third-party tools (EBI)
  • Great documentation & built-in testing at

eq & jq, best friends for life

						$ # syntax-highlighting for item JSON data
						$ eq item a7edaf1b-f853-4b6d-b8a6-e402f0fd2f58 | jq
						$ # open 10 most recent items in your web browser
						$ eq search | jq '.results[].links.view' | xargs open

fx is great, too

eq item $UUID | fx
fx showing JSON for an item with one attachment's properties shown and another's collapsed

Example: course list taxonomies

We have a huge course lists project which converts course information into a series of departmental taxonomies, turning them into vocabularly lists and a hierarchical course structure that our users can browse when contributing items.

course list taxonomies pt. II

eq finds our taxonomy UUIDs, using a consistent naming convention to look them up

						for dept in $depts
						    set tax "$dept - COURSE LIST"
						    set uuid (eq tax --name $tax | jq -r '.uuid')
						    if [ $uuid ]
						        uptaxo --tid $uuid --csv \

Example: items without titles

eq search -l 50 | jq '.results[] | (.links.view, .name)' \
| ack '^null$' -A 1

Above: last 50 items. Below: loop for last 1,000 items.

						$ for $IDX in (seq 0 19)
						>   eq search --length 50 --start (math $IDX x 50) | \
						>   jq '.results[] | (.links.view, .name)' | \
						>   ack '^null$' --after-context 1 | sed '/null/d'
						> end

Miscellaneous Shortcuts

$ eq launch # run the admin console launcher script
$ eq login # fill in login page in a web browser
$ eq settings diagnostics # open user diagnostics
$ eq apidocs # open the API documentation

Limitations & warnings

  • There are few tests but I'm writing more
  • Does not lock resources before modification (but you could manually)
  • Unable to download items complete with files
  • Rare blind spots in the APIs, many more in eq


Thank you for having me! I can be reached at phette23 on most platforms (Twitter, Gmail, GitHub).