{"_id":"@beomsukoh/zotero-cli","_rev":"5-24f009f890670b22173ac0bc3a61861d","name":"@beomsukoh/zotero-cli","dist-tags":{"latest":"0.5.1"},"versions":{"0.2.0":{"name":"@beomsukoh/zotero-cli","version":"0.2.0","license":"MIT","_id":"@beomsukoh/zotero-cli@0.2.0","maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"bin":{"zt":"dist/cli.js"},"dist":{"shasum":"5739e4a49b15b683ec6af40c50b7de1b6b04825a","tarball":"https://registry.npmjs.org/@beomsukoh/zotero-cli/-/zotero-cli-0.2.0.tgz","fileCount":29,"integrity":"sha512-dF1bUYnRlmy1L71gEUkYSDTei1Tmt8DCGjAEvMXehWR2dypbyvhbesHljTMgn6kE79Xcfmrc/L3A5YvV/xv+GQ==","signatures":[{"sig":"MEQCIHPJ7XdPzTi7HZuM2wwZMMdK7QEEgruON3KIv7betEGWAiAxLHSurKTy2Ju1kRZ1bC2SJ5tyndR8h+JdzDfQwtnglw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62153},"type":"module","engines":{"node":">=20"},"gitHead":"c4da81b3a387800d575e981a3b04bc0ae0830e86","scripts":{"dt":"tsx ./src/cli.ts","test":"vitest run","build":"node ./scripts/build.mjs","check":"tsc --noEmit && node ./scripts/validate-docs.mjs","prepack":"pnpm build","pack:check":"pnpm build && npm pack --dry-run","test:smoke":"vitest run --config vitest.config.smoke.ts","release:check":"pnpm check && pnpm test && pnpm build && pnpm pack:check","prepublishOnly":"pnpm check && pnpm test && pnpm pack:check"},"_npmUser":{"name":"beomsukoh","email":"gobeumsu@gmail.com"},"_npmVersion":"10.9.2","description":"Pure CLI wrapper for the Zotero API.","directories":{},"_nodeVersion":"22.16.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/zotero-cli_0.2.0_1773989259600_0.5244061385641663","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@beomsukoh/zotero-cli","version":"0.3.0","license":"MIT","_id":"@beomsukoh/zotero-cli@0.3.0","maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"bin":{"zt":"dist/cli.js"},"dist":{"shasum":"3ea7af43528ebbe810f591ff431b3c13df49a149","tarball":"https://registry.npmjs.org/@beomsukoh/zotero-cli/-/zotero-cli-0.3.0.tgz","fileCount":30,"integrity":"sha512-5dH0MzvkRTy0aDXSia9p2V1MjspKSLtJ51B7ZoPNby210JK2nCgAu9A1+YWbEq2vY8pMbK/14xZFOoUmq2VK7A==","signatures":[{"sig":"MEUCIAOXxNePkmAXSTrXhM2o1j8ni1+gy9dbFbZYVd5Mq7pfAiEAk0DW8VrItOnd57CRe2CzEIPeYXuc4Rq58RpyIcsE11c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70094},"type":"module","engines":{"node":">=20"},"gitHead":"659d3fc512eda648f725335d9581b4e400f91c55","scripts":{"dt":"tsx ./src/cli.ts","test":"vitest run","build":"node ./scripts/build.mjs","check":"tsc --noEmit && node ./scripts/validate-docs.mjs","prepack":"pnpm build","pack:check":"pnpm build && npm pack --dry-run","test:smoke":"vitest run --config vitest.config.smoke.ts","release:check":"pnpm check && pnpm test && pnpm build && pnpm pack:check","prepublishOnly":"pnpm check && pnpm test && pnpm pack:check"},"_npmUser":{"name":"beomsukoh","email":"gobeumsu@gmail.com"},"_npmVersion":"10.9.2","description":"Pure CLI wrapper for the Zotero API.","directories":{},"_nodeVersion":"22.16.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/zotero-cli_0.3.0_1773989686791_0.8610199821272222","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@beomsukoh/zotero-cli","version":"0.4.0","license":"MIT","_id":"@beomsukoh/zotero-cli@0.4.0","maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"bin":{"zt":"dist/cli.js"},"dist":{"shasum":"c2432922ac84dc62ff69936c8451b2bf6c6f7636","tarball":"https://registry.npmjs.org/@beomsukoh/zotero-cli/-/zotero-cli-0.4.0.tgz","fileCount":33,"integrity":"sha512-VZZVEsdFBeKTmy2hz7vK0wVNaksXDGHuFtdQkro8a1tKf1jPbKsFwxF96KXRmGSIc+S959MVQiwckfLFlibFlQ==","signatures":[{"sig":"MEQCIHhqU7YlRzuY66vsJ936/OytH+BQ0MkaPElLyxWNuwoUAiBpVqYq/c8c0n96ys83GbdzJHBAQBF4ep0ONthpeSDbPw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":83471},"type":"module","engines":{"node":">=20"},"gitHead":"99c64b57820aa9295e430ba4d375e7908c3ea2ed","scripts":{"dt":"tsx ./src/cli.ts","test":"vitest run","build":"node ./scripts/build.mjs","check":"tsc --noEmit && node ./scripts/validate-docs.mjs","prepack":"pnpm build","pack:check":"pnpm build && npm pack --dry-run","test:smoke":"vitest run --config vitest.config.smoke.ts","release:check":"pnpm check && pnpm test && pnpm build && pnpm pack:check","prepublishOnly":"pnpm check && pnpm test && pnpm pack:check"},"_npmUser":{"name":"beomsukoh","email":"gobeumsu@gmail.com"},"_npmVersion":"10.9.2","description":"Pure CLI wrapper for the Zotero API.","directories":{},"_nodeVersion":"22.16.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/zotero-cli_0.4.0_1773992635108_0.8245935726665374","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@beomsukoh/zotero-cli","version":"0.5.0","license":"MIT","_id":"@beomsukoh/zotero-cli@0.5.0","maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"bin":{"zt":"dist/cli.js"},"dist":{"shasum":"7b62d3c8edfec79d39e11c286acdfc63073ef66a","tarball":"https://registry.npmjs.org/@beomsukoh/zotero-cli/-/zotero-cli-0.5.0.tgz","fileCount":37,"integrity":"sha512-nOXwkfnkjTwrXllQeVnBbORGfDOw/n8xe2bGzR+GAsUkVU9rwVB2zNzoFA9uAJyuVhtyWUSQ0ht3ELTyYI82Mg==","signatures":[{"sig":"MEYCIQDC7jAyT+nevyO021PcHFhB04G2OJF7oU/lh5bsHYElNAIhAKjIHuJoqheiKCPN8DjdnqMnfC90aGaIyxHr+L/NE8Y6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114243},"type":"module","engines":{"node":">=20"},"gitHead":"a32bed325343cb377009aa2f3defe576680a344a","scripts":{"dt":"tsx ./src/cli.ts","test":"vitest run","build":"node ./scripts/build.mjs","check":"tsc --noEmit && node ./scripts/validate-docs.mjs","prepack":"pnpm build","pack:check":"pnpm build && npm pack --dry-run","test:smoke":"vitest run --config vitest.config.smoke.ts","release:check":"pnpm check && pnpm test && pnpm build && pnpm pack:check","prepublishOnly":"pnpm check && pnpm test && pnpm pack:check"},"_npmUser":{"name":"beomsukoh","email":"gobeumsu@gmail.com"},"_npmVersion":"10.9.2","description":"Pure CLI wrapper for the Zotero API.","directories":{},"_nodeVersion":"22.16.0","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/zotero-cli_0.5.0_1774083842811_0.4935595510064956","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@beomsukoh/zotero-cli","version":"0.5.1","description":"Pure CLI wrapper for the Zotero API.","type":"module","bin":{"zt":"dist/cli.js"},"scripts":{"build":"node ./scripts/build.mjs","check":"tsc --noEmit && node ./scripts/validate-docs.mjs","dt":"tsx ./src/cli.ts","test":"vitest run","test:smoke":"vitest run --config vitest.config.smoke.ts","release:check":"pnpm check && pnpm test && pnpm build && pnpm pack:check","pack:check":"pnpm build && npm pack --dry-run","prepack":"pnpm build","prepublishOnly":"pnpm check && pnpm test && pnpm pack:check"},"engines":{"node":">=20"},"license":"MIT","devDependencies":{"@types/node":"^22.0.0","tsx":"^4.0.0","typescript":"^5.7.0","vitest":"^4.0.0"},"_id":"@beomsukoh/zotero-cli@0.5.1","gitHead":"cb12729d99816bcf3104bb85085223fd1774912d","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-meFRRQhVSGUIWEB09SCi0dWMnz1AH3DSyXADFxbCGpFutcMcGNteZya8aRTv1eQGM0wQ1BgCCJw9rqPyDHwU4g==","shasum":"675f07cffd493188a52ab7fdf6189dff1f3d4450","tarball":"https://registry.npmjs.org/@beomsukoh/zotero-cli/-/zotero-cli-0.5.1.tgz","fileCount":37,"unpackedSize":114241,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB6qsoRDHD/CC/1XpXptl8M9aJJSa8lE+mDx0qId/oyUAiEApNkjI1TRbX1eZXOsRdHOoqi0rOLE2q+LxdYSkUMmljA="}]},"_npmUser":{"name":"beomsukoh","email":"gobeumsu@gmail.com"},"directories":{},"maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zotero-cli_0.5.1_1774084072924_0.45706564159835317"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T06:47:39.545Z","modified":"2026-03-21T09:07:53.216Z","0.2.0":"2026-03-20T06:47:39.773Z","0.3.0":"2026-03-20T06:54:46.926Z","0.4.0":"2026-03-20T07:43:55.250Z","0.5.0":"2026-03-21T09:04:02.972Z","0.5.1":"2026-03-21T09:07:53.084Z"},"license":"MIT","description":"Pure CLI wrapper for the Zotero API.","maintainers":[{"name":"beomsukoh","email":"gobeumsu@gmail.com"}],"readme":"# Zotero CLI\n\nControl Zotero from the command line. `zotero-cli` wraps the Zotero Web API v3 and Local API through shell-friendly verbs, JSON output, and a consistent option grammar.\n\n```bash\n# Search your library\nzt search \"machine learning\" --limit 5\n\n# Import a paper by DOI\nzt import --doi \"10.1145/3025453.3025912\"\n\n# Export as BibTeX\nzt export --format bibtex --collection ABCD1234\n```\n\n## Requirements\n\n- Node.js 20+\n- Zotero 7+ (for local API reads) or a Zotero API key (for writes)\n- [Zotero Translation Server](https://github.com/zotero/translation-server) (optional, for `zt import`)\n\n## Install\n\n```bash\nnpm install -g @beomsukoh/zotero-cli\n```\n\nVerify the installation:\n\n```bash\nzt items --limit 1\n```\n\nThis prints a JSON array of items from your local Zotero library. If Zotero desktop is not running, the command exits with an error.\n\n## Quickstart\n\nList items in your library:\n\n```bash\nzt items --limit 10 --sort dateAdded\n```\n\nSearch across your library:\n\n```bash\nzt search \"attention is all you need\"\n```\n\nGet a specific item by key:\n\n```bash\nzt get ABCD1234\n```\n\nList collections:\n\n```bash\nzt collections\n```\n\nImport a paper by DOI (requires Translation Server):\n\n```bash\ndocker run -d -p 1969:1969 zotero/translation-server\nzt import --doi \"10.1145/3025453.3025912\"\n```\n\nAttach a PDF to an existing item:\n\n```bash\nzt attach ./paper.pdf --key ABCD1234\n```\n\nExport your library as BibTeX:\n\n```bash\nzt export --format bibtex\n```\n\n## Architecture\n\nZotero CLI supports three modes of operation:\n\n| Mode | Reads | Writes | Auth | Setup |\n|---|---|---|---|---|\n| **Local** (default) | Local API | — | None | Zero config |\n| **Local + Debug Bridge** | Local API | Debug Bridge | Token | `zt setup --fix` |\n| **Web** | Web API | Web API | API key | Manual |\n\n**Local mode** requires no configuration — just have Zotero desktop running. Reads work out of the box.\n\n**Local + Debug Bridge** enables local writes (create, attach, link, delete) via the [Debug Bridge](https://github.com/retorquere/zotero-better-bibtex/releases/tag/debug-bridge) plugin. This is a standalone 219-line Zotero plugin (no BBT dependency) that lets the CLI execute JavaScript inside Zotero:\n\n```bash\n# One-time setup\nzt setup --fix\n\n# Now writes work locally\nzt create:item --type journalArticle --title \"My Paper\"\nzt link paper.pdf --parent \"My Paper\" --recognize\n```\n\n**Web mode** requires an API key from [zotero.org/settings/keys](https://www.zotero.org/settings/keys/):\n\n```bash\nexport ZOTERO_API_KEY=your_key_here\nexport ZOTERO_USER_ID=12345\nexport ZOTERO_BASE_URL=https://api.zotero.org\n```\n\n### Configuration\n\n| Variable | Default | Description |\n|---|---|---|\n| `ZOTERO_BASE_URL` | `http://localhost:23119/api` | API base URL |\n| `ZOTERO_API_KEY` | — | API key (Web mode writes) |\n| `ZOTERO_USER_ID` | `0` | User ID (`0` = local) |\n| `ZOTERO_TRANSLATION_SERVER` | `http://localhost:1969` | Translation Server URL |\n| `ZOTERO_DEBUG_BRIDGE_TOKEN` | — | Debug Bridge token (local writes) |\n\n## Commands\n\n### Core\n\n| Command | Description |\n|---|---|\n| `zt items` | List items (`--collection`, `--top`, `--tag`, `--type`, `--limit`, `--sort`) |\n| `zt collections` | List collections (`--parent` for subcollections) |\n| `zt get <key>` | Get item by key (`--children` for attachments/notes) |\n| `zt search <query>` | Search items (`--qmode`, `--tag`, `--type`) |\n| `zt tags` | List tags |\n| `zt libraries` | List group libraries |\n| `zt delete --key <key>` | Delete item or collection (`--collection` flag) |\n| `zt attach <file> --key <key>` | Upload and attach file to item |\n| `zt link <file>` | Link a file without copying (`--parent`, `--recognize`) |\n| `zt export --format <fmt>` | Export items in citation formats |\n| `zt fulltext <key>` | Get full-text content of an item |\n| `zt import` | Import from DOI, ISBN, arXiv, URL, BibTeX, or PDF |\n\n### Create\n\n| Command | Description |\n|---|---|\n| `zt create:item` | Create item from JSON or `--type`/`--title`/`--doi` options |\n| `zt create:collection <name>` | Create collection (`--parent` for nesting) |\n\n### Lookup\n\n| Command | Description |\n|---|---|\n| `zt types [itemType]` | List item types, or fields/creators for a type |\n| `zt template <itemType>` | Get JSON template for item creation |\n\n### Other\n\n| Command | Description |\n|---|---|\n| `zt setup` | Check and configure Debug Bridge (`--fix` to auto-configure) |\n\nRun `zt --help` or `zt <command> --help` for full usage.\n\n## Examples\n\n### Import a paper by DOI and attach its PDF\n\n```bash\n# Start translation server (one-time)\ndocker run -d -p 1969:1969 zotero/translation-server\n\n# Import: resolves metadata via Translation Server, creates item, attaches PDF\nzt import ./paper.pdf --doi \"10.1145/3025453.3025912\" --collection COLL1234\n```\n\n### Import from arXiv\n\n```bash\nzt import --arxiv \"2301.01234\"\n```\n\n### Import from a BibTeX file\n\n```bash\nzt import --bibtex ./references.bib\n```\n\n### Link a local PDF (no copy)\n\n```bash\n# Standalone linked file — Zotero auto-recognizes metadata\nzt link paper.pdf --recognize\n\n# Link to an existing item by title\nzt link paper.pdf --parent \"Attention Is All You Need\"\n\n# Link with direct key (for scripts)\nzt link paper.pdf --key ABCD1234\n```\n\n### Create a journal article manually\n\n```bash\n# Get the template first\nzt template journalArticle\n\n# Create with specific fields\nzt create:item --type journalArticle \\\n  --title \"My Research Paper\" \\\n  --doi \"10.1234/example\" \\\n  --date \"2026\" \\\n  --collection COLL1234\n```\n\n### Create from raw JSON\n\n```bash\nzt create:item '{\"itemType\":\"book\",\"title\":\"Clean Code\",\"creators\":[{\"creatorType\":\"author\",\"firstName\":\"Robert\",\"lastName\":\"Martin\"}]}'\n```\n\n### Browse item type schema\n\n```bash\n# List all 42 item types\nzt types\n\n# Show fields for journal articles\nzt types journalArticle\n\n# Show creator types for books\nzt types book --creators\n```\n\n### Export a collection as CSL-JSON\n\n```bash\nzt export --format csljson --collection ABCD1234\n```\n\n### Export Formats\n\n`bibtex`, `biblatex`, `ris`, `csljson`, `csv`, `tei`, `wikipedia`, `mods`, `refer`\n\n### Work with group libraries\n\n```bash\n# List groups\nzt libraries\n\n# List items in a group\nzt items --group 12345\n\n# Search within a group\nzt search \"deep learning\" --group 12345\n```\n\n## Philosophy\n\n`zotero-cli` exposes what the Zotero API provides. It does not add citation management workflows, sync logic, bibliography generation pipelines, or PDF management beyond attachment upload. If the Zotero API does not offer a behavior natively, this package does not invent one.\n\nThe `import` command integrates with the official [Zotero Translation Server](https://github.com/zotero/translation-server) for DOI/ISBN/URL resolution — the same engine that powers the Zotero Connector browser extension.\n\n## Development\n\n```bash\npnpm install\npnpm check          # TypeScript + doc validation\npnpm test           # Unit tests\npnpm build\npnpm pack:check     # Package integrity\n```\n\n## Publishing\n\n```bash\npnpm release:check\nnpm publish --access public\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}