Zowie<img width="10%" align="right" src="https://github.com/mhucka/zowie/raw/main/.graphics/zowie-icon.png">

Zowie ("Zotero link writer") is a command-line program for macOS that writes Zotero select links into the file attachments contained in a Zotero database.

Table of contents

• Introduction
• Installation
• Usage
• Known issues and limitations
• Additional tips
• Getting help
• Contributing
• License
• Acknowledgments

Introduction

When using Zotero, you may on occasion want to work with PDF files and other attachment files outside of Zotero. For example, if you're a DEVONthink user, you will at some point discover the power of indexing your local Zotero database from DEVONthink. However, when viewing or manipulating the attachments from outside of Zotero, you may run into the following problem: when looking at a given file, how do you find out which Zotero entry it belongs to?

Enter Zowie (a loose acronym for "Zotero link writer", and pronounced like the interjection). Zowie scans through the files on your disk in a local Zotero database, looks up the Zotero bibliographic record corresponding to each file found, and writes a Zotero select link into the file and/or certain macOS Finder/Spotlight metadata fields (depending on the user's choice). A Zotero select link has the form zotero://select/... and when opened on macOS, causes the Zotero desktop application to open that item in your database. Zowie thus makes it possible to go from a file opened in an application other than Zotero (e.g., DEVONthink, Adobe Acrobat), to the Zotero record corresponding to that file.

Regretfully, Zowie can only work with Zotero libraries that use normal/local data storage; it cannot work when Zotero is configured to use linked attachments.

Installation

There are multiple ways of installing Zowie, ranging from downloading a self-contained, single-file, ready-to-run program, to installing it as a typical Python program using pip. Please choose the alternative that suits you and your Mac environment.

Alternative 1: downloading the ready-to-run program

On macOS Catalina (10.15) or later, you can use a ready-to-run version of Zowie that only needs a Python interpreter version 3.8 or higher on your computer. That's the case for macOS 10.15 and later, but before you can use it, you may need to let macOS install some additional software components from Apple. To test it, run the following command in a terminal and take note of the version of Python that it prints:

python3 --version

If this is the first time you've run python3 on your system, macOS will either ask you if you want to install certain additional software components, or it may produce an error about xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools) .... In either case, the solution is to run the following command in the terminal:

xcode-select --install

In the pop-up dialog box that this brings up, click the Install button and agree to let it install the Command Line Tools package from Apple.

Next,

1. <img align="right" width="350px" src="https://github.com/mhucka/zowie/raw/develop/.graphics/shiv-releases.png"/>Go to the latest release on GitHub and find the Assets
2. Download the ZIP file whose name contains the version of Python on your computer (which you determined by running python3 --version above)
3. Unzip the file (if your browser didn't unzip it)
4. Open the folder that gets created (it will have a name like zowie-1.2.0-macos-python3.8)
5. Look inside for zowie and move it to a location where you put other command-line programs (such as /usr/local/bin).

If you want to put it in /usr/local/bin but that folder does not exist on your computer yet, you can create it by opening a terminal window and running the following command (prior to moving zowie into /usr/local/bin):

sudo mkdir /usr/local/bin

The following is an example command that you can type in a terminal to move Zowie there:

sudo mv zowie /usr/local/bin

Alternative 2: installing Zowie using pipx

You can use pipx to install Zowie. Pipx will install it into a separate Python environment that isolates the dependencies needed by Zowie from other Python programs on your system, and yet the resulting zowie command wil be executable from any shell – like any normal program on your computer. If you do not already have pipx on your system, it can be installed in a variety of easy ways and it is best to consult Pipx's installation guide for instructions. Once you have pipx on your system, you can install Zowie with the following command:

pipx install zowie

Pipx can also let you run Zowie directly using pipx run zowie, although in that case, you must always prefix every Zowie command with pipx run. Consult the documentation for pipx run for more information.

Alternative 3: installing Zowie using pip

The instructions below assume you have a Python 3 interpreter installed on your computer. Note that the default on macOS at least through 10.14 (Mojave) is Python 2 – please first install Python version 3 and familiarize yourself with running Python programs on your system before proceeding further.

You should be able to install zowie with pip for Python 3. To install zowie from the Python package repository (PyPI), run the following command:

python3 -m pip install zowie

As an alternative to getting it from PyPI, you can use pip to install zowie directly from GitHub:

python3 -m pip install git+https://github.com/mhucka/zowie.git

If you already installed Zowie once before, and want to update to the latest version, add --upgrade to the end of either command line above.

Alternative 4: installing Zowie from sources

If you prefer to install Zowie directly from the source code, you can do that too. To get a copy of the files, you can clone the GitHub repository:

git clone https://github.com/mhucka/zowie

Alternatively, you can download the files as a ZIP archive using this link directly from your browser using this link: https://github.com/mhucka/zowie/archive/refs/heads/main.zip

Next, after getting a copy of the files, run setup.py inside the code directory:

cd zowie
python3 setup.py install

Usage

For help with usage at any time, run zowie with the option -h.

The zowie command-line program should end up installed in a location where software is normally installed on your computer, if the installation steps described in the previous section proceeded successfully. Running Zowie from a terminal shell then should be as simple as running any other shell command on your system:

zowie -h

If you installed it as a Python package, then an alternative method is available to run Zowie from anywhere, namely to use the normal approach for running Python modules:

python3 -m zowie -h

Credentials for Zotero access

Zowie relies on the Zotero sync API to get information about your references. This allows it to look up Zotero item URIs for files regardless of whether they belong to your personal library or shared libraries, and from there, construct the appropriate Zotero select link for the files. If you do not already have a Zotero sync account, it will be necessary to create one before going any further.

To use Zowie, you will also need both an API user identifier (also known as the userID) and an API key. To find out your Zotero userID and create a new API key, log in to your Zotero account at Zotero.org and visit the Feeds/API tab of the your Settings page. On that page you can find your userID and create a new API key for Zowie.

The first time you run Zowie, it will ask for this information and (unless the -K option is given) store it in your macOS keychain so that it does not have to ask for it again on future occasions. It is also possible to supply the identifier and API key directly on the command line using the -i and -a options, respectively; the given values will then override any values stored in the keychain and (unless the -K option is also given) will be used to