{"id":50950487,"url":"https://github.com/victortomaili/mendeley-cli","last_synced_at":"2026-06-18T01:00:17.651Z","repository":{"id":364765420,"uuid":"1267876625","full_name":"VictorTomaili/mendeley-cli","owner":"VictorTomaili","description":"AI-agent-friendly CLI \u0026 JavaScript SDK for the Mendeley API","archived":false,"fork":false,"pushed_at":"2026-06-17T23:06:20.000Z","size":708,"stargazers_count":3,"open_issues_count":49,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T01:00:14.900Z","etag":null,"topics":["academic","ai-agent","bibtex","citation","cli","mendeley","nodejs","oauth2","reference-manager","scholar","sdk"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VictorTomaili.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-12T23:57:44.000Z","updated_at":"2026-06-17T23:05:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VictorTomaili/mendeley-cli","commit_stats":null,"previous_names":["victortomaili/mendeley-cli"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/VictorTomaili/mendeley-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictorTomaili%2Fmendeley-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictorTomaili%2Fmendeley-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictorTomaili%2Fmendeley-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictorTomaili%2Fmendeley-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VictorTomaili","download_url":"https://codeload.github.com/VictorTomaili/mendeley-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictorTomaili%2Fmendeley-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34471639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["academic","ai-agent","bibtex","citation","cli","mendeley","nodejs","oauth2","reference-manager","scholar","sdk"],"created_at":"2026-06-18T01:00:16.883Z","updated_at":"2026-06-18T01:00:17.642Z","avatar_url":"https://github.com/VictorTomaili.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🔬 mendeley-cli\n\n**AI-agent-friendly CLI \u0026 JavaScript SDK for the Mendeley API**\n\n[![Node.js \u003e= 22](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org/)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n_Query 100 M+ academic papers, manage your library, export BibTeX — from the terminal._\n\n[Getting started](#getting-started) · [CLI reference](#cli-reference) · [Library API](#library-api) · [AI agents](#built-for-ai-agents)\n\n\u003c/div\u003e\n\n---\n\n\u003e [!IMPORTANT]\n\u003e **This is an unofficial, community-maintained project.**\n\u003e `mendeley-cli` is **not** affiliated with, endorsed by, or sponsored by\n\u003e Mendeley Ltd. or Elsevier. **Mendeley** and the Mendeley logo are trademarks\n\u003e of Mendeley Ltd. All trademarks are the property of their respective owners.\n\u003e\n\u003e By using this tool you confirm that you have read and accept the\n\u003e **[Mendeley Terms of Use](https://www.elsevier.com/legal/elsevier-mendeley-terms-and-conditions)**\n\u003e and the **[Elsevier Website Terms \u0026 Conditions](https://www.elsevier.com/legal/elsevier-website-terms-and-conditions)**.\n\u003e You are solely responsible for how you use this software and for complying\n\u003e with Mendeley's usage policies, rate limits, and applicable laws.\n\u003e\n\u003e Looking for the **official** resources?\n\u003e\n\u003e - Official website: **https://www.mendeley.com**\n\u003e - Official API docs: **https://dev.mendeley.com/**\n\u003e - Official Python SDK: **https://github.com/mendeley/mendeley-python-sdk**\n\n---\n\n## Why this exists\n\nThe official Mendeley SDK is Python-only and hasn't been updated in years. This project provides:\n\n- **A shell CLI** (`mendeley`) that defaults to **text output** (LLM/human-friendly), with `--format json|tsv|ids` available for scripting and `jq`\n- **A JavaScript library** (`import { Mendeley } from 'mendeley-cli'`) for Node.js 22+\n- **Zero dependencies** (pure Node.js, no runtime deps)\n- **PKCE auth** with automatic token refresh — log in once, stay logged in\n- **73 help pages** with examples, plus a `--skill` flag that dumps the full command surface as Markdown for LLM system prompts\n\n## Getting started\n\n```bash\n# Install globally (recommended)\nnpm install -g mendeley-cli\n\n# Or run directly from source\ngit clone https://github.com/VictorTomaili/mendeley-cli.git\ncd mendeley-cli\nnpm install\nnpm link        # makes 'mendeley' available system-wide\n```\n\n### Calling `mendeley` from another language (Python, etc.) on Windows\n\nOn Windows, `npm install -g` (or `pnpm add -g`) installs the\n`mendeley` command as a **`mendeley.CMD`** shim. Windows'\n`CreateProcess` (the native process launcher used by Python's\n`subprocess.run`, Node's `child_process.spawn`, and most other\nnon-shell callers) does **not** auto-execute `.CMD` files — only\nthe CMD shell does. As a result, a bare call like\n`subprocess.run([\"mendeley\", \"--version\"])` fails with\n`FileNotFoundError: [WinError 2]`, even though `mendeley --version`\nworks fine in any Windows terminal (#105).\n\n**Fix — pick one of these:**\n\n```python\nimport subprocess, shutil\n\n# Option A (recommended): resolve the full path to the .CMD shim\nmendeley = shutil.which(\"mendeley.cmd\") or shutil.which(\"mendeley\")\nsubprocess.run([mendeley, \"--version\"])\n\n# Option B: pass shell=True (works, but with quoting/security caveats)\nsubprocess.run([\"mendeley\", \"--version\"], shell=True)\n\n# Option C: call node directly on the installed entry point\nimport subprocess, sys\nnode = sys.executable  # or hard-code the Node.js path\n# Find the installed bin/mendeley.js (adjust the global prefix path)\nsubprocess.run([node, r\"C:\\\\Users\\\\me\\\\AppData\\\\Roaming\\\\npm\\\\node_modules\\\\mendeley-cli\\\\bin\\\\mendeley.js\", \"--version\"])\n```\n\nIn Node.js, the equivalent is `spawn(mendeleyPath, args, {shell: true})`\nor resolving the `.cmd` path explicitly.\n\nThis only affects Windows and only non-shell callers. Linux and\nmacOS are unaffected (the shebang `#!/usr/bin/env node` is honoured).\n\n### Configure credentials\n\nGet your client ID at [dev.mendeley.com](https://dev.mendeley.com/):\n\n```bash\nmendeley auth set clientId YOUR_CLIENT_ID\nmendeley auth set clientSecret YOUR_CLIENT_SECRET\nmendeley auth set redirectUri http://localhost:11595\n```\n\n### Authenticate\n\nThe CLI does **not** open a browser or run a local callback server. It prints\nthe authorisation URL and prompts you to paste the redirect URL back after\nlogging in:\n\n```bash\nmendeley auth login\n# 1. Open the printed URL in a browser and complete the Mendeley login\n# 2. After approving, the browser redirects to http://localhost:…\n#    (\"This site can't be reached\" is normal — the CLI isn't listening)\n# 3. Copy the ENTIRE URL from the browser address bar\n# 4. Paste it at the prompt\n```\n\nFor headless servers / CI / AI agents, use the two-step flow instead:\n\n```bash\nmendeley auth url                    # prints a login URL + saves PKCE verifier\n# ... visit URL in any browser, log in, copy the redirect URL ...\nmendeley auth exchange \"http://localhost:11595/?code=...\u0026state=...\"\n```\n\n### Verify\n\n```bash\nmendeley whoami\n```\n\n## CLI reference\n\nEvery command supports `--help` with full usage, options, and examples:\n\n```bash\nmendeley --help                       # top-level help\nmendeley documents list --help        # per-command help\nmendeley --skill                      # full API as a skill document (for AI system prompts)\n```\n\n### Output formats\n\n| Flag                        | Format                 | Use case                  |\n| --------------------------- | ---------------------- | ------------------------- |\n| `--format text` _(default)_ | Key-value              | Quick reading, LLM use    |\n| `--format json`             | JSON                   | AI agents, piping to `jq` |\n| `--format tsv`              | Tab-separated          | Spreadsheet import        |\n| `--format ids`              | Bare IDs, one per line | Piping to `xargs`         |\n\n### Commands\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eauth\u003c/strong\u003e — manage authentication\u003c/summary\u003e\n\n```\nmendeley auth login                  # print URL, paste redirect URL back (no browser)\nmendeley auth logout                 # delete saved token\nmendeley auth status                 # show config (no secrets)\nmendeley auth whoami                 # test token via /profiles/me\nmendeley auth url                    # print login URL (headless step 1)\nmendeley auth exchange \u003curl|code\u003e    # exchange code for token (headless step 2)\nmendeley auth set \u003ckey\u003e \u003cvalue\u003e      # set clientId, clientSecret, redirectUri, host\nmendeley auth unset \u003ckey\u003e            # remove a credential\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ecatalog\u003c/strong\u003e — browse the global Mendeley catalog (100 M+ papers)\u003c/summary\u003e\n\n```\nmendeley catalog search \"machine learning\" --limit 10\nmendeley catalog by-doi 10.1038/nature14539\nmendeley catalog by-identifier --arxiv 1706.03762\nmendeley catalog lookup --title \"Attention is all you need\"\nmendeley catalog advanced-search --author Hinton --min-year 2017\nmendeley catalog get \u003cid\u003e\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003edocuments\u003c/strong\u003e — manage documents in your library\u003c/summary\u003e\n\n```\nmendeley documents list --limit 50 --all\nmendeley documents get \u003cid\u003e\nmendeley documents search \"deep learning\"\nmendeley documents advanced-search --author LeCun --min-year 2018\nmendeley documents create --title \"My Paper\" --type journal\nmendeley documents create-from-file ./paper.pdf\nmendeley documents update \u003cid\u003e --data '{\"title\":\"New Title\"}'\nmendeley documents delete \u003cid\u003e\nmendeley documents move-to-trash \u003cid\u003e\nmendeley documents attach-file \u003cid\u003e ./supplement.pdf\nmendeley documents add-note \u003cid\u003e \"important finding\"\nmendeley documents annotations \u003cid\u003e\nmendeley documents files \u003cid\u003e\nmendeley documents export-bibtex \u003cid\u003e\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003elibrary\u003c/strong\u003e — high-level library operations\u003c/summary\u003e\n\n```\nmendeley library export-bibtex --out refs.bib\nmendeley library export-json --out library.json\nmendeley library dedupe --by doi\nmendeley library stats\nmendeley library recent --limit 5\nmendeley library by-tag \"to-read\"\nmendeley library add-by-doi 10.1038/nature14539\nmendeley library add-by-arxiv 1706.03762\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003efolders · groups · files · annotations · trash · profile\u003c/strong\u003e\u003c/summary\u003e\n\n```\nmendeley folders list --all\nmendeley folders create \"Reading List\" --parent \u003cid\u003e\nmendeley folders documents \u003cfolderId\u003e\nmendeley folders add-document \u003cfolderId\u003e \u003cdocId\u003e\n\nmendeley groups list\nmendeley groups members \u003cgroupId\u003e\nmendeley groups documents \u003cgroupId\u003e\n\nmendeley files list --document \u003cdocId\u003e\nmendeley files download \u003cfileId\u003e /tmp/papers\n\nmendeley annotations list --document \u003cdocId\u003e\nmendeley annotations get \u003cid\u003e\nmendeley annotations update \u003cid\u003e --data '{\"text\":\"updated\"}'\nmendeley annotations delete \u003cid\u003e\n\nmendeley trash list\nmendeley trash get \u003cid\u003e\nmendeley trash restore \u003cid\u003e\nmendeley trash delete \u003cid\u003e --yes\nmendeley trash empty --yes\n\nmendeley profile me\nmendeley profile get \u003cid\u003e\n```\n\n\u003c/details\u003e\n\n## Library API\n\nUse the SDK programmatically in any Node.js 22+ project:\n\n```bash\nnpm install mendeley-cli\n```\n\n```js\nimport { Mendeley } from 'mendeley-cli';\n\nconst mendeley = new Mendeley({\n  clientId: 'YOUR_CLIENT_ID',\n  clientSecret: 'YOUR_CLIENT_SECRET',\n  redirectUri: 'http://localhost:11595',\n});\n\n// Client-credentials flow (no user interaction)\nconst session = await mendeley.startClientCredentialsFlow().authenticate();\n\n// Search the catalog\nconst results = await session.catalog.search('machine learning', { view: 'all' });\nconst page = await results.list({ pageSize: 10 });\nconsole.log(`Found ${(await page.items).length} results`);\n\n// Look up by DOI\nconst doc = await session.catalog.byIdentifier({ doi: '10.1038/nature14539' });\nconsole.log(doc.title); // \"Deep learning\"\nconsole.log(doc.year); // 2015\n```\n\n### Authorization-code flow with PKCE\n\n```js\nconst flow = await mendeley.startAuthorizationCodeFlowAsync({ usePkce: true });\nconsole.log('Visit:', flow.getLoginUrl());\n\n// ... user completes login in browser ...\nconst session = await flow.authenticate(authorizationCode);\nconst me = await session.profiles.me;\nconsole.log(`Hello, ${me.first_name}`);\n```\n\n## Built for AI agents\n\nThe CLI is designed as a **tool** that AI agents can call directly. Key design decisions:\n\n1. **Text by default, JSON on demand** — output defaults to LLM/human-friendly text; pass `--format json` for machine-parseable output\n2. **`--skill` flag** — prints the entire CLI surface as a Markdown document you can paste into a system prompt:\n\n   ```bash\n   mendeley --skill \u003e MENDELEY_SKILL.md\n   ```\n\n3. **Structured errors** — errors are JSON objects with `ok: false` and a human-readable `error` field\n4. **Headless auth** — no browser is opened; the agent can run `mendeley auth login` to get a URL, or `mendeley auth url` + `mendeley auth exchange` for a two-step flow\n5. **Every command documented** — `--help` shows synopsis, description, options, arguments, and at least one example\n\n### Example: AI agent workflow\n\n```\nAgent: I'll search the Mendeley catalog for papers about CRISPR.\n\n$ mendeley catalog search \"CRISPR gene editing\" --limit 5 --format ids\n\u003e 436fcd07-37bf-36d8-9d86-3f073872c69d\n\u003e a105c9f1-b55f-382a-a4ce-90241d15ec77\n\u003e ...\n\nAgent: Found 5 papers. Let me get details on the first one.\n\n$ mendeley catalog get 436fcd07-37bf-36d8-9d86-3f073872c69d --format json\n\u003e { \"title\": \"Current applications and future perspective of CRISPR/Cas9 ...\", ... }\n\nAgent: Would you like me to add this to your library?\n\n$ mendeley library add-by-doi 10.1186/s12943-022-01518-8 --format json\n\u003e { \"ok\": true, \"id\": \"...\", \"title\": \"...\" }\n```\n\n## Environment variables\n\n| Variable                 | Description                                       |\n| ------------------------ | ------------------------------------------------- |\n| `MENDELEY_CLIENT_ID`     | OAuth client ID (overrides credentials.json)      |\n| `MENDELEY_CLIENT_SECRET` | OAuth client secret                               |\n| `MENDELEY_REDIRECT_URI`  | OAuth redirect URI                                |\n| `MENDELEY_HOST`          | API base URL (default `https://api.mendeley.com`) |\n| `MENDELEY_CONFIG`        | Path to `credentials.json`                        |\n| `MENDELEY_TOKEN_FILE`    | Path to `token.json`                              |\n\n## Development\n\n```bash\ngit clone https://github.com/VictorTomaili/mendeley-cli.git\ncd mendeley-cli\nnpm install\nnpm link          # install global 'mendeley' command (symlink — edits are live)\n\nnpm test          # run the full test suite (unit + integration)\nnpm run test:unit\nnpm run test:integration\n```\n\nNo build step — this is plain ESM JavaScript targeting Node.js 22+.\n\n### Project structure\n\n```\nbin/mendeley.js         CLI entry point\nlib/cli/                CLI framework (command parser, output, credentials)\n  commands/             One file per top-level subcommand\nsrc/                    JavaScript SDK\n  client.js             Mendeley class — entry point\n  session.js            MendeleySession — authenticated resource container\n  auth.js               OAuth flow helpers (auth-code, client-credentials, PKCE)\n  resources/            REST resource classes\n  models/               JSON model classes with lazy fields\n  pagination.js         Page iterator\n  response.js           ResponseObject, LazyResponseObject\ntest/                   unit + integration tests\n```\n\n## Security\n\nPlease **do not** file public GitHub issues for suspected vulnerabilities.\nSee [SECURITY.md](SECURITY.md) for the supported versions, how to report a\nvulnerability privately, and our response timeline. Reports can be opened\nvia [GitHub Security Advisories](https://github.com/VictorTomaili/mendeley-cli/security/advisories/new)\nor emailed to the maintainer.\n\n## License\n\n[Apache-2.0](LICENSE)\n\n## Disclaimer\n\n`mendeley-cli` is an **unofficial, community-maintained** project. It is **not**\naffiliated with, endorsed by, or sponsored by **Mendeley Ltd.** or **Elsevier**.\n**Mendeley** and the Mendeley logo are trademarks of Mendeley Ltd.; all other\ntrademarks are the property of their respective owners.\n\nBy installing or using this software you confirm that you have read and accept\nthe **[Mendeley Terms of Use](https://www.elsevier.com/legal/elsevier-mendeley-terms-and-conditions)**\nand the **[Elsevier Website Terms \u0026 Conditions](https://www.elsevier.com/legal/elsevier-website-terms-and-conditions)**.\nYou are solely responsible for:\n\n- complying with Mendeley's usage policies, acceptable-use rules, and rate limits;\n- keeping your OAuth credentials, access tokens, and refresh tokens secure;\n- ensuring your use of the API and any retrieved content complies with applicable\n  copyrights, licences, and laws.\n\nThe authors and contributors of this project provide the software **\"as is\"**\n(see the Apache-2.0 licence) and accept **no responsibility or liability** for\nany misuse, data loss, account suspension, or other consequence arising from\nits use.\n\n### Official resources\n\nIf you need vendor-supported tooling, please use the official resources:\n\n- Official website: **\u003chttps://www.mendeley.com\u003e**\n- Official API documentation (Developer Portal): **\u003chttps://dev.mendeley.com/\u003e**\n- Official Python SDK: **\u003chttps://github.com/mendeley/mendeley-python-sdk\u003e**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictortomaili%2Fmendeley-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvictortomaili%2Fmendeley-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvictortomaili%2Fmendeley-cli/lists"}