🔬 mendeley-cli

AI-agent-friendly CLI & JavaScript SDK for the Mendeley API

Query 100 M+ academic papers, manage your library, export BibTeX — from the terminal.

Getting started · CLI reference · Library API · AI agents

[!IMPORTANT] This is an unofficial, community-maintained project. mendeley-cli is not affiliated with, endorsed by, or sponsored by Mendeley Ltd. or Elsevier. Mendeley and the Mendeley logo are trademarks of Mendeley Ltd. All trademarks are the property of their respective owners.

By using this tool you confirm that you have read and accept the Mendeley Terms of Use and the Elsevier Website Terms & Conditions. You are solely responsible for how you use this software and for complying with Mendeley's usage policies, rate limits, and applicable laws.

Looking for the official resources?

• Official website: https://www.mendeley.com
• Official API docs: https://dev.mendeley.com/
• Official Python SDK: https://github.com/mendeley/mendeley-python-sdk

Why this exists

The official Mendeley SDK is Python-only and hasn't been updated in years. This project provides:

• A shell CLI (mendeley) that defaults to text output (LLM/human-friendly), with --format json|tsv|ids available for scripting and jq
• A JavaScript library (import { Mendeley } from 'mendeley-cli') for Node.js 22+
• Zero dependencies (pure Node.js, no runtime deps)
• PKCE auth with automatic token refresh — log in once, stay logged in
• 73 help pages with examples, plus a --skill flag that dumps the full command surface as Markdown for LLM system prompts

Getting started

# Install globally (recommended)
npm install -g mendeley-cli

# Or run directly from source
git clone https://github.com/VictorTomaili/mendeley-cli.git
cd mendeley-cli
npm install
npm link        # makes 'mendeley' available system-wide

Calling mendeley from another language (Python, etc.) on Windows

On Windows, npm install -g (or pnpm add -g) installs the mendeley command as a mendeley.CMD shim. Windows' CreateProcess (the native process launcher used by Python's subprocess.run, Node's child_process.spawn, and most other non-shell callers) does not auto-execute .CMD files — only the CMD shell does. As a result, a bare call like subprocess.run(["mendeley", "--version"]) fails with FileNotFoundError: [WinError 2], even though mendeley --version works fine in any Windows terminal (#105).

Fix — pick one of these:

import subprocess, shutil

# Option A (recommended): resolve the full path to the .CMD shim
mendeley = shutil.which("mendeley.cmd") or shutil.which("mendeley")
subprocess.run([mendeley, "--version"])

# Option B: pass shell=True (works, but with quoting/security caveats)
subprocess.run(["mendeley", "--version"], shell=True)

# Option C: call node directly on the installed entry point
import subprocess, sys
node = sys.executable  # or hard-code the Node.js path
# Find the installed bin/mendeley.js (adjust the global prefix path)
subprocess.run([node, r"C:\\Users\\me\\AppData\\Roaming\\npm\\node_modules\\mendeley-cli\\bin\\mendeley.js", "--version"])

In Node.js, the equivalent is spawn(mendeleyPath, args, {shell: true}) or resolving the .cmd path explicitly.

This only affects Windows and only non-shell callers. Linux and macOS are unaffected (the shebang #!/usr/bin/env node is honoured).

Configure credentials

Get your client ID at dev.mendeley.com:

mendeley auth set clientId YOUR_CLIENT_ID
mendeley auth set clientSecret YOUR_CLIENT_SECRET
mendeley auth set redirectUri http://localhost:11595

Authenticate

The CLI does not open a browser or run a local callback server. It prints the authorisation URL and prompts you to paste the redirect URL back after logging in:

mendeley auth login
# 1. Open the printed URL in a browser and complete the Mendeley login
# 2. After approving, the browser redirects to http://localhost:…
#    ("This site can't be reached" is normal — the CLI isn't listening)
# 3. Copy the ENTIRE URL from the browser address bar
# 4. Paste it at the prompt

For headless servers / CI / AI agents, use the two-step flow instead:

mendeley auth url                    # prints a login URL + saves PKCE verifier
# ... visit URL in any browser, log in, copy the redirect URL ...
mendeley auth exchange "http://localhost:11595/?code=...&state=..."

Verify

mendeley whoami

CLI reference

Every command supports --help with full usage, options, and examples:

mendeley --help                       # top-level help
mendeley documents list --help        # per-command help
mendeley --skill                      # full API as a skill document (for AI system prompts)

Output formats

| Flag | Format | Use case | | --------------------------- | ---------------------- | ------------------------- | | --format text (default) | Key-value | Quick reading, LLM use | | --format json | JSON | AI agents, piping to jq | | --format tsv | Tab-separated | Spreadsheet import | | --format ids | Bare IDs, one per line | Piping to xargs |

Commands

mendeley auth login                  # print URL, paste redirect URL back (no browser)
mendeley auth logout                 # delete saved token
mendeley auth status                 # show config (no secrets)
mendeley auth whoami                 # test token via /profiles/me
mendeley auth url                    # print login URL (headless step 1)
mendeley auth exchange <url|code>    # exchange code for token (headless step 2)
mendeley auth set <key> <value>      # set clientId, clientSecret, redirectUri, host
mendeley auth unset <key>            # remove a credential

mendeley catalog search "machine learning" --limit 10
mendeley catalog by-doi 10.1038/nature14539
mendeley catalog by-identifier --arxiv 1706.03762
mendeley catalog lookup --title "Attention is all you need"
mendeley catalog advanced-search --author Hinton --min-year 2017
mendeley catalog get <id>

mendeley documents list --limit 50 --all
mendeley documents get <id>
mendeley documents search "deep learning"
mendeley documents advanced-search --author LeCun --min-year 2018
mendeley documents create --title "My Paper" --type journal
mendeley documents create-from-file ./paper.pdf
mendeley documents update <id> --data '{"title":"New Title"}'
mendeley documents delete <id>
mendeley documents move-to-trash <id>
mendeley documents attach-file <id> ./supplement.pdf
mendeley documents add-note <id> "important finding"
mendeley documents annotations <id>
mendeley documents files <id>
mendeley documents export-bibtex <id>

mendeley library export-bibtex --out refs.bib
mendeley library export-json --out library.json
mendeley library dedupe --by doi
mendeley library stats
mendeley library recent --limit 5
mendeley library by-tag "to-read"
mendeley library add-by-doi 10.1038/nature14539
mendeley library add-by-arxiv 1706.03762

mendeley folders list --all
mendeley folders create "Reading List" --parent <id>
mendeley folders documents <folderId>
mendeley folders add-document <folderId> <docId>

mendeley groups list
mendeley groups members <groupId>
mendeley groups documents <groupId>

mendeley files list --document <docId>
mendeley files download <fileId> /tmp/papers

mendeley annotations list --document <docId>
mendeley annotations get <id>
mendeley annotations update <id> --data '{"text":"updated"}'
mendeley annotations delete <id>

mendeley trash list
mendeley trash get <id>
mendeley trash restore <id>
mendeley trash delete <id> --yes
mendeley trash empty --yes

mendeley profile me
mendeley profile get <id>

Library API

Use the SDK programmatically in any Node.js 22+ project:

npm install mendeley-cli

import { Mendeley } from 'mendeley-cli';

const mendeley = new Mendeley({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  redirectUri: 'http://localhost:11595',
});

// Client-credentials flow (no user interaction)
const session = await mendeley.startClientCredentialsFlow().authenticate();

// Search the catalog
const results = await session.catalog.search('machine learning', { view: 'all' });
const page = await results.list({ pageSize: 10 });
console.log(`Found ${(await page.items).length} results`);

// Look up by DOI
const doc = await session.catalog.byIdentifier({ doi: '10.1038/nature14539' });
console.log(doc.title); // "Deep learning"
console.log(doc.year); // 2015

Authorization-code flow with PKCE

const flow = await mendeley.startAuthorizationCodeFlowAsync({ usePkce: true });
console.log('Visit:', flow.getLoginUrl());

// ... user completes login in browser ...
const session = await flow.authenticate(authorizationCode);
const me = await session.profiles.me;
console.log(`Hello, ${me.first_name}`);

Built for AI agents

The CLI is designed as a tool that AI agents can call directly. Key design decisions:

1. Text by default, JSON on demand — output defaults to LLM/human-friendly text; pass --format json for machine-parseable output

2. --skill flag — prints the entire CLI surface as a Markdown document you can paste into a system prompt:

   mendeley --skill > MENDELEY_SKILL.md

3. Structured errors — errors are JSON objects with ok: false and a human-readable error field

4. 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

5. Every command documented — --help shows synopsis, description, options, arguments, and at least one example

Example: AI agent workflow

Agent: I'll search the Mendeley catalog for papers about CRISPR.

$ mendeley catalog search "CRISPR gene editing" --limit 5 --format ids
> 436fcd07-37bf-36d8-9d86-3f073872c69d
> a105c9f1-b55f-382a-a4ce-90241d15ec77
> ...

Agent: Found 5 papers. Let me get details on the first one.

$ mendeley catalog get 436fcd07-37bf-36d8-9d86-3f073872c69d --format json
> { "title": "Current applications and future perspective of CRISPR/Cas9 ...", ... }

Agent: Would you like me to add this to your library?

$ mendeley library add-by-doi 10.1186/s12943-022-01518-8 --format json
> { "ok": true, "id": "...", "title": "..." }

Environment variables

| Variable | Description | | ------------------------ | ------------------------------------------------- | | MENDELEY_CLIENT_ID | OAuth client ID (overrides credentials.json) | | MENDELEY_CLIENT_SECRET | OAuth client secret | | MENDELEY_REDIRECT_URI | OAuth redirect URI | | MENDELEY_HOST | API base URL (default https://api.mendeley.com) | | MENDELEY_CONFIG | Path to credentials.json | | MENDELEY_TOKEN_FILE | Path to token.json |

Development

git clone https://github.com/VictorTomaili/mendeley-cli.git
cd mendeley-cli
npm install
npm link          # install global 'mendeley' command (symlink — edits are live)

npm test          # run the full test suite (unit + integration)
npm run test:unit
npm run test:integration

No build step — this is plain ESM JavaScript targeting Node.js 22+.

Project structure

bin/mendeley.js         CLI entry point
lib/cli/                CLI framework (command parser, output, credentials)
  commands/             One file per top-level subcommand
src/                    JavaScript SDK
  client.js             Mendeley class — entry point
  session.js            MendeleySession — authenticated resource container
  auth.js               OAuth flow helpers (auth-code, client-credentials, PKCE)
  resources/            REST resource classes
  models/               JSON model classes with lazy fields
  pagination.js         Page iterator
  response.js           ResponseObject, LazyResponseObject
test/                   unit + integration tests

Security

Please do not file public GitHub issues for suspected vulnerabilities. See SECURITY.md for the supported versions, how to report a vulnerability privately, and our response timeline. Reports can be opened via GitHub Security Advisories or emailed to the maintainer.

License

Apache-2.0

Disclaimer

mendeley-cli is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or sponsored by Mendeley Ltd. or Elsevier. Mendeley and the Mendeley logo are trademarks of Mendeley Ltd.; all other trademarks are the property of their respective owners.

By installing or using this software you confirm that you have read and accept the Mendeley Terms of Use and the Elsevier Website Terms & Conditions. You are solely responsible for:

• complying with Mendeley's usage policies, acceptable-use rules, and rate limits;
• keeping your OAuth credentials, access tokens, and refresh tokens secure;
• ensuring your use of the API and any retrieved content complies with applicable copyrights, licences, and laws.

The authors and contributors of this project provide the software "as is" (see the Apache-2.0 licence) and accept no responsibility or liability for any misuse, data loss, account suspension, or other consequence arising from its use.

Official resources

If you need vendor-supported tooling, please use the official resources:

• Official website: https://www.mendeley.com
• Official API documentation (Developer Portal): https://dev.mendeley.com/
• Official Python SDK: https://github.com/mendeley/mendeley-python-sdk