Zotero Categorise

A command-line tool to manage Zotero collections by placing items into specific collections based on their title, description, and tags.

Configuration

To create a zotero-cli.toml file, follow these steps:

1. Open the terminal and create the zotero-cli.toml file using the nano text editor:

   mkdir -p ~/.config/zotero-cli
   nano ~/.config/zotero-cli/zotero-cli.toml

2. Inside the zotero-cli.toml file, add the following content:

   api-key = "YOUR_ZOTERO_API_KEY"
   group-id = 123
   library-type = "group"
   indent = 4
   

Installation

To use this tool, you need to have Node.js installed on your system. You can install the required dependencies and run the tool with the following steps:

Clone this repository to your local machine:

git clone https://github.com/OpenDevEd/Zotero-Categorise.git
cd Zotero-Categorise
npm install

Binary

The package includes a binary zotero-categorise. You can install this with

npm build
npm link

If you do that, you can use zotero-categorise below.

Usage

Help works in the usual way

zotero-categorise
zotero-categorise -h
zotero-categorise collection -h
zotero-categorise generate -h
zotero-categorise collectionByJson -h

The collection command

You can use the collection command to place items into collections.

Here are the available options:

zotero-categorise collection -c <collection> -i <item...>

or

zotero-categorise collection -c zotero://select/groups/${Group-id}/collections/${CollectionId} -i zotero://select/Groups//${group-id}/items/${ItemId}

In this command, the option have this function:

• -c, --collection <collection>: The id of a collection, which has sub-collections in which you want to place the items.
• -i, --item [item...]: One or more Item Ids that you want to place in the collection.
• --itemsfromcollection <collection>: Process items in the provided collection.
• --itemswithtag <tag>: Process items with this tag.
• --itemswithouttag <tag>: Process items that do not have this tag.
• --itemsfromlibrary: Process all items in the library.

For example, if your collection structure is this:

Countries
- Sierra Leone
- Zambia
- Zimbabwe

Then by providing the collection id for 'Countries', items will be matched against Sierra Leone, Zambia, Zimbabwe, and placed in those collections.

Generating Keyword-Collection Mapping

The generate command allows you to create a JSON file that maps keywords to collections. This mapping is useful for automating the categorization process by periodically scanning your Zotero items.

zotero-categorise generate -- -c [collection1] [collection2]

Options:

• -g, --group [group]: Specifies the Zotero group ID to work with.
• -c, --collection [collection...]: Lists the Zotero collection IDs to include in the mapping.
• -n, --name [name]: (Optional) Specifies the name of the JSON file that will be generated (default is 'list.json').

Categorize Items from JSON File

The collectionByJson command enables you to categorize items from a JSON file into Zotero collections.

zotero-categorise collectionByJson -- -j [json file] -i [item...]

Options:

• -j, --json [json]: Specifies the JSON file that contains the keyword-collection mapping.
• -i, --item [item...]: One or more Item Ids that you want to categorize into collections.
• --itemsfromcollection <collection>: Process items in the provided collection.
• --itemswithtag <tag>: Process items with this tag.
• --itemswithouttag <tag>: Process items that do not have this tag.
• --itemsfromlibrary: Process all items in the library.
• -t, --test: Use test mode, which does not actually place items in the collection. This is useful for verification and testing.