<p align="center"><img src="https://github.com/dhondta/zotero-cli/raw/main/docs/pages/imgs/logo.png"></p>
<h1 align="center">Zotero CLI <a href="https://twitter.com/intent/tweet?text=Zotero%20CLI%20-%20A%20Tinyscript%20tool%20for%20sorting,%20ranking%20and%20exporting%20Zotero%20references%20based%20on%20pyzotero.%0D%0Ahttps%3a%2f%2fgithub%2ecom%2fdhondta%2fzotero-cli%0D%0A&hashtags=python,zotero,cli,pyzotero,pagerank"><img src="https://img.shields.io/badge/Tweet--lightgrey?logo=twitter&style=social" alt="Tweet" height="20"/></a></h1>
<h3 align="center">Sort and rank your Zotero references easy from your CLI.<br>Ask questions to your Zotero documents with GPT locally.</h3>
[](https://pypi.python.org/pypi/zotero-cli-tool/)
[](https://pypi.python.org/pypi/zotero-cli-tool/)
[](https://github.com/dhondta/zotero-cli/actions/workflows/publish-package.yml)
[](https://zotero-cli.readthedocs.io/en/latest/?badge=latest)
[](https://snyk.io/test/github/dhondta/zotero-cli?targetFile=requirements.txt)
[](https://zenodo.org/badge/latestdoi/321932121)
[](https://pypi.python.org/pypi/zotero-cli-tool/)
This [Tinyscript](https://github.com/dhondta/python-tinyscript) tool relies on [`pyzotero`](https://github.com/urschrei/pyzotero) for communicating with [Zotero's Web API](https://www.zotero.org/support/dev/web_api/v3/start). It allows to list field values, show items in tables in the CLI or also export sorted items to an Excel file.
```session
$ pip install zotero-cli-tool
```
## Quick Start
The first time you start it, the tool will ask for your API identifier and key. It will cache it to `~/.zotero/creds.txt` with permissions set to `rw` for your user only. Data is cached to `~/.zotero/cache/`. If you are using a shared group library, you can either pass the "`-g`" ("`--group`") option in your `zotero-cli` command or, for setting it permanently, touch an empty file `~/.zotero/group`.
- Manually update cached data
```sh
$ zotero-cli reset
```
Note that it could take a while. That's why caching is interesting for further use.
- Count items in a collection
```sh
$ zotero-cli count --filter "collections:biblio"
123
```
- List values for a given field
```sh
$ zotero-cli list itemType
Type
----
computer program
conference paper
document
journal article
manuscript
thesis
webpage
```
- Show entries with the given set of fields, filtered based on multiple critera and limited to a given number of items
```sh
$ zotero-cli show year title itemType numPages --filter "collections:biblio" --filter "title:detect" --limit ">date:10"
Year Title Type #Pages
---- ----- ---- ------
2016 Classifying Packed Programs as Malicious Software Detected conference paper 3
2016 Detecting Packed Executable File: Supervised or Anomaly Detection Method? conference paper 5
2016 Entropy analysis to classify unknown packing algorithms for malware detection conference paper 21
2017 Packer Detection for Multi-Layer Executables Using Entropy Analysis journal article 18
2018 Sensitive system calls based packed malware variants detection using principal component initialized MultiLayers neural networks journal article 13
2018 Effective, efficient, and robust packing detection and classification journal article 15
2019 Efficient automatic original entry point detection journal article 14
2019 All-in-One Framework for Detection, Unpacking, and Verification for Malware Analysis journal article 16
2020 Experimental Comparison of Machine Learning Models in Malware Packing Detection conference paper 3
2020 Building a smart and automated tool for packed malware detections using machine learning thesis 99
```
- Export entries
```sh
$ zotero-cli export year title itemType numPages --filter "collections:biblio" --filter "title:detect" --limit ">date:10"
$ file export.xlsx
export.xlsx: Microsoft Excel 2007+
```
> **Supported formats**: `csv`, `html`, `json`, `md` (Markdown), `rst` (RestructuredText), `xml`, `xslx`, `yaml`
> Get help with `zotero-cli export --help`
- Use a predefined query
```sh
$ zotero-cli show - --query "top-50-most-relevants"
```
> **Note**: "`-`" is used for the `field` positional argument to tell the tool to select the predefined list of fields included in the query.
This is equivalent to:
```sh
$ zotero-cli show year title numPages itemType --limit ">rank:50"
```
Available queries:
- `no-attachment`: list of all items with no attachment ; displayed fields: `title`
- `no-url`: list of all items with no URL ; displayed fields: `year`, `title`
- `top-10-most-relevants`: top-10 best ranked items ; displayed fields: `year`, `title`, `numPages`, `itemType`
- `top-50-most-relevants`: same as top-10 but with the top-50
Mark items:
```sh
$ zotero-cli mark read --filter "title:a nice paper"
$ zotero-cli mark unread --filter "title:a nice paper"
```
> **Markers**:
>
> - `read` / `unread`: by default, items are displayed in bold ; marking an item as read will make it display as normal
> - `irrelevant` / `relevant`: this allows to exclude a result from the output list of items
> - `ignore` / `unignore`: this allows to completely ignore an item, including in the ranking algorithm
## Local GPT
This feature is based on [PrivateGPT](https://github.com/imartinez/privateGPT). It can be used to ingest local Zotero documents and ask questions based on a chosen GPT model.
- Install optional dependencies
```sh
$ pip install zotero-cli-tool[gpt]
```
- Install a model among the followings:
- `ggml-gpt4all-j-v1.3-groovy.bin` (default)
- `ggml-gpt4all-l13b-snoozy.bin`
- `ggml-mpt-7b-chat.bin`
- `ggml-v3-13b-hermes-q5_1.bin`
- `ggml-vicuna-7b-1.1-q4_2.bin`
- `ggml-vicuna-13b-1.1-q4_2.bin`
- `ggml-wizardLM-7B.q4_2.bin`
- `ggml-stable-vicuna-13B.q4_2.bin`
- `ggml-mpt-7b-base.bin`
- `ggml-nous-gpt4-vicuna-13b.bin`
- `ggml-mpt-7b-instruct.bin`
- `ggml-wizard-13b-uncensored.bin`
```sh
$ zotero-cli install
```
The latest installed model gets selected for the `ask` command (see hereafter).
- Ingest your documents
```sh
$ zotero-cli ingest
```
- Ask questions to your documents
```sh
$ zotero-cli ask
Using embedded DuckDB with persistence: data will be stored in: /home/morfal/.zotero/db
Found model file.
[...]
Enter a query:
```
## Special Features
Some additional fields can be used for listing/filtering/showing/exporting data.
- Computed fields
- `authors`: the list of `creators` with `creatorType` equal to `author`
- `citations`: the number of relations the item has to other items with a later date
- `editors`: the list of `creators` with `creatorType` equal to `editor`
- `numAttachments`: the number of child items with `itemType` equal to `attachment`
- `numAuthors`: the number of `creators` with `creatorType` equal to `author`
- `numCreators`: the number of `creators`
- `numEditors`: the number of `creators` with `creatorType` equal to `editor`
- `numNotes`: the number of child items with `itemType` equal to `note`
- `numPages`: the (corrected) number of pages, either got from the original or `pages` field
- `references`: the number of relations the item has to other items with an earlier date
- `year`: the year coming from the `datetime` parsing of the `date` field
- Extracted fields (from the `extra` field)
- `comments`: custom field for adding comments
- `results`: custom field for mentioning results related to the item
- `what`: custom field for a short description of what the item is about
- `zscc`: number of Scholar citations, computed with the [Zotero Google Scholar Citations](https://github.com/beloglazov/zotero-scholar-citations) plugin
- PageRank-based reference ranking algorithm
- `rank`: computed field aimed to rank references in order of relevance ; this uses an algorithm similar to Google's PageRank while weighting references in function of their year of publication (giving more importance to recent references, which cannot have as much citations as older references anyway)
Raw data
{
"_id": null,
"home_page": null,
"name": "zotero-cli-tool",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "zotero, citations, cli-app, tinyscript",
"author": null,
"author_email": "Alexandre D'Hondt <alexandre.dhondt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e0/2b/701f4eb51e73b3ead61f9454d85337b9cddc4c755bd971350a2bd4170576/zotero_cli_tool-1.7.4.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img src=\"https://github.com/dhondta/zotero-cli/raw/main/docs/pages/imgs/logo.png\"></p>\n<h1 align=\"center\">Zotero CLI <a href=\"https://twitter.com/intent/tweet?text=Zotero%20CLI%20-%20A%20Tinyscript%20tool%20for%20sorting,%20ranking%20and%20exporting%20Zotero%20references%20based%20on%20pyzotero.%0D%0Ahttps%3a%2f%2fgithub%2ecom%2fdhondta%2fzotero-cli%0D%0A&hashtags=python,zotero,cli,pyzotero,pagerank\"><img src=\"https://img.shields.io/badge/Tweet--lightgrey?logo=twitter&style=social\" alt=\"Tweet\" height=\"20\"/></a></h1>\n<h3 align=\"center\">Sort and rank your Zotero references easy from your CLI.<br>Ask questions to your Zotero documents with GPT locally.</h3>\n\n[](https://pypi.python.org/pypi/zotero-cli-tool/)\n\n[](https://pypi.python.org/pypi/zotero-cli-tool/)\n[](https://github.com/dhondta/zotero-cli/actions/workflows/publish-package.yml)\n[](https://zotero-cli.readthedocs.io/en/latest/?badge=latest)\n[](https://snyk.io/test/github/dhondta/zotero-cli?targetFile=requirements.txt)\n[](https://zenodo.org/badge/latestdoi/321932121)\n[](https://pypi.python.org/pypi/zotero-cli-tool/)\n\nThis [Tinyscript](https://github.com/dhondta/python-tinyscript) tool relies on [`pyzotero`](https://github.com/urschrei/pyzotero) for communicating with [Zotero's Web API](https://www.zotero.org/support/dev/web_api/v3/start). It allows to list field values, show items in tables in the CLI or also export sorted items to an Excel file.\n\n\n```session\n$ pip install zotero-cli-tool\n```\n\n## Quick Start\n\nThe first time you start it, the tool will ask for your API identifier and key. It will cache it to `~/.zotero/creds.txt` with permissions set to `rw` for your user only. Data is cached to `~/.zotero/cache/`. If you are using a shared group library, you can either pass the \"`-g`\" (\"`--group`\") option in your `zotero-cli` command or, for setting it permanently, touch an empty file `~/.zotero/group`.\n\n- Manually update cached data\n\n```sh\n$ zotero-cli reset\n```\n\nNote that it could take a while. That's why caching is interesting for further use.\n\n- Count items in a collection\n\n```sh\n$ zotero-cli count --filter \"collections:biblio\"\n123\n```\n\n- List values for a given field\n\n```sh\n$ zotero-cli list itemType\n\n Type \n ---- \n computer program \n conference paper \n document \n journal article \n manuscript \n thesis \n webpage \n\n```\n\n- Show entries with the given set of fields, filtered based on multiple critera and limited to a given number of items\n\n```sh\n$ zotero-cli show year title itemType numPages --filter \"collections:biblio\" --filter \"title:detect\" --limit \">date:10\"\n\n Year Title Type #Pages \n ---- ----- ---- ------ \n 2016 Classifying Packed Programs as Malicious Software Detected conference paper 3 \n 2016 Detecting Packed Executable File: Supervised or Anomaly Detection Method? conference paper 5 \n 2016 Entropy analysis to classify unknown packing algorithms for malware detection conference paper 21 \n 2017 Packer Detection for Multi-Layer Executables Using Entropy Analysis journal article 18 \n 2018 Sensitive system calls based packed malware variants detection using principal component initialized MultiLayers neural networks journal article 13 \n 2018 Effective, efficient, and robust packing detection and classification journal article 15 \n 2019 Efficient automatic original entry point detection journal article 14 \n 2019 All-in-One Framework for Detection, Unpacking, and Verification for Malware Analysis journal article 16 \n 2020 Experimental Comparison of Machine Learning Models in Malware Packing Detection conference paper 3 \n 2020 Building a smart and automated tool for packed malware detections using machine learning thesis 99 \n\n```\n\n- Export entries\n\n```sh\n$ zotero-cli export year title itemType numPages --filter \"collections:biblio\" --filter \"title:detect\" --limit \">date:10\"\n$ file export.xlsx \nexport.xlsx: Microsoft Excel 2007+\n\n```\n\n> **Supported formats**: `csv`, `html`, `json`, `md` (Markdown), `rst` (RestructuredText), `xml`, `xslx`, `yaml`\n> Get help with `zotero-cli export --help`\n\n- Use a predefined query\n\n```sh\n$ zotero-cli show - --query \"top-50-most-relevants\"\n```\n\n> **Note**: \"`-`\" is used for the `field` positional argument to tell the tool to select the predefined list of fields included in the query.\n\nThis is equivalent to:\n\n```sh\n$ zotero-cli show year title numPages itemType --limit \">rank:50\"\n```\n\nAvailable queries:\n- `no-attachment`: list of all items with no attachment ; displayed fields: `title`\n- `no-url`: list of all items with no URL ; displayed fields: `year`, `title`\n- `top-10-most-relevants`: top-10 best ranked items ; displayed fields: `year`, `title`, `numPages`, `itemType`\n- `top-50-most-relevants`: same as top-10 but with the top-50\n\nMark items:\n\n```sh\n$ zotero-cli mark read --filter \"title:a nice paper\"\n$ zotero-cli mark unread --filter \"title:a nice paper\"\n```\n\n> **Markers**:\n> \n> - `read` / `unread`: by default, items are displayed in bold ; marking an item as read will make it display as normal\n> - `irrelevant` / `relevant`: this allows to exclude a result from the output list of items\n> - `ignore` / `unignore`: this allows to completely ignore an item, including in the ranking algorithm\n\n\n## Local GPT\n\nThis feature is based on [PrivateGPT](https://github.com/imartinez/privateGPT). It can be used to ingest local Zotero documents and ask questions based on a chosen GPT model.\n\n- Install optional dependencies\n\n```sh\n$ pip install zotero-cli-tool[gpt]\n```\n\n- Install a model among the followings:\n\n - `ggml-gpt4all-j-v1.3-groovy.bin` (default)\n - `ggml-gpt4all-l13b-snoozy.bin`\n - `ggml-mpt-7b-chat.bin`\n - `ggml-v3-13b-hermes-q5_1.bin`\n - `ggml-vicuna-7b-1.1-q4_2.bin`\n - `ggml-vicuna-13b-1.1-q4_2.bin`\n - `ggml-wizardLM-7B.q4_2.bin`\n - `ggml-stable-vicuna-13B.q4_2.bin`\n - `ggml-mpt-7b-base.bin`\n - `ggml-nous-gpt4-vicuna-13b.bin`\n - `ggml-mpt-7b-instruct.bin`\n - `ggml-wizard-13b-uncensored.bin`\n\n```sh\n$ zotero-cli install\n```\n\nThe latest installed model gets selected for the `ask` command (see hereafter).\n\n- Ingest your documents\n\n```sh\n$ zotero-cli ingest\n```\n\n- Ask questions to your documents\n\n```sh\n$ zotero-cli ask\nUsing embedded DuckDB with persistence: data will be stored in: /home/morfal/.zotero/db\nFound model file.\n[...]\nEnter a query: \n\n```\n\n\n## Special Features\n\nSome additional fields can be used for listing/filtering/showing/exporting data.\n\n- Computed fields\n\n - `authors`: the list of `creators` with `creatorType` equal to `author`\n - `citations`: the number of relations the item has to other items with a later date\n - `editors`: the list of `creators` with `creatorType` equal to `editor`\n - `numAttachments`: the number of child items with `itemType` equal to `attachment`\n - `numAuthors`: the number of `creators` with `creatorType` equal to `author`\n - `numCreators`: the number of `creators`\n - `numEditors`: the number of `creators` with `creatorType` equal to `editor`\n - `numNotes`: the number of child items with `itemType` equal to `note`\n - `numPages`: the (corrected) number of pages, either got from the original or `pages` field\n - `references`: the number of relations the item has to other items with an earlier date\n - `year`: the year coming from the `datetime` parsing of the `date` field\n\n- Extracted fields (from the `extra` field)\n\n - `comments`: custom field for adding comments\n - `results`: custom field for mentioning results related to the item\n - `what`: custom field for a short description of what the item is about\n - `zscc`: number of Scholar citations, computed with the [Zotero Google Scholar Citations](https://github.com/beloglazov/zotero-scholar-citations) plugin\n\n- PageRank-based reference ranking algorithm\n\n - `rank`: computed field aimed to rank references in order of relevance ; this uses an algorithm similar to Google's PageRank while weighting references in function of their year of publication (giving more importance to recent references, which cannot have as much citations as older references anyway)\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Tinyscript tool for sorting and exporting Zotero references based on pyzotero",
"version": "1.7.4",
"project_urls": {
"homepage": "https://github.com/dhondta/zotero-cli",
"issues": "https://github.com/dhondta/zotero-cli/issues",
"repository": "https://github.com/dhondta/zotero-cli"
},
"split_keywords": [
"zotero",
" citations",
" cli-app",
" tinyscript"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4e807020f07562c23b47750bfbc7895c7f985c3c54d3b95c258de90b6f2e35a1",
"md5": "7f70d54346f6acefab3d8c9548db4b9f",
"sha256": "27c9d8bab7afac8d7a3473b46e404ee053dd7633aa43572c9ee15e70a8c7ff55"
},
"downloads": -1,
"filename": "zotero_cli_tool-1.7.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f70d54346f6acefab3d8c9548db4b9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 36631,
"upload_time": "2025-08-07T00:40:30",
"upload_time_iso_8601": "2025-08-07T00:40:30.225212Z",
"url": "https://files.pythonhosted.org/packages/4e/80/7020f07562c23b47750bfbc7895c7f985c3c54d3b95c258de90b6f2e35a1/zotero_cli_tool-1.7.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e02b701f4eb51e73b3ead61f9454d85337b9cddc4c755bd971350a2bd4170576",
"md5": "96e2e7463c77b27dd15377aa38c5aa4a",
"sha256": "ec9502930f12e88a15a71b7436f4e04d4dd816349d96ec0bbad88b404dac9c70"
},
"downloads": -1,
"filename": "zotero_cli_tool-1.7.4.tar.gz",
"has_sig": false,
"md5_digest": "96e2e7463c77b27dd15377aa38c5aa4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 67008,
"upload_time": "2025-08-07T00:40:31",
"upload_time_iso_8601": "2025-08-07T00:40:31.470025Z",
"url": "https://files.pythonhosted.org/packages/e0/2b/701f4eb51e73b3ead61f9454d85337b9cddc4c755bd971350a2bd4170576/zotero_cli_tool-1.7.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 00:40:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dhondta",
"github_project": "zotero-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "chromadb",
"specs": []
},
{
"name": "fonttools",
"specs": [
[
">=",
"4.43.0"
]
]
},
{
"name": "gpt4all",
"specs": []
},
{
"name": "langchain",
"specs": [
[
">=",
"0.0.225"
]
]
},
{
"name": "llama-cpp-python",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "numpy",
"specs": [
[
">=",
"1.22.2"
]
]
},
{
"name": "pyzotero",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "sympy",
"specs": [
[
">=",
"1.12"
]
]
},
{
"name": "tinyscript",
"specs": [
[
">=",
"1.30.16"
]
]
},
{
"name": "tqdm",
"specs": []
},
{
"name": "xlsxwriter",
"specs": []
},
{
"name": "pillow",
"specs": [
[
">=",
"10.2.0"
]
]
},
{
"name": "fastapi",
"specs": [
[
">=",
"0.109.1"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.32.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
">=",
"1.26.19"
]
]
},
{
"name": "zipp",
"specs": [
[
">=",
"3.19.1"
]
]
}
],
"lcname": "zotero-cli-tool"
}
JSON
