@beomsukoh/zotero-cli 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,23 @@
-# zotero-cli
+# Zotero CLI
 
-Pure CLI wrapper for the Zotero API. Supports both the local desktop API (read-only, no auth) and the web API (full CRUD with API key).
+Control 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.
 
-Same architecture as [devonthink-cli](https://github.com/GoBeromsu/devonthink-cli): CommandModule pattern, port/adapter, typed error hierarchy. Zero runtime dependencies.
+```bash
+# Search your library
+zt search "machine learning" --limit 5
+
+# Import a paper by DOI
+zt import --doi "10.1145/3025453.3025912"
+
+# Export as BibTeX
+zt export --format bibtex --collection ABCD1234
+```
+
+## Requirements
+
+- Node.js 20+
+- Zotero 7+ (for local API reads) or a Zotero API key (for writes)
+- [Zotero Translation Server](https://github.com/zotero/translation-server) (optional, for `zt import`)
 
 ## Install
 
@@ -10,74 +25,87 @@ Same architecture as [devonthink-cli](https://github.com/GoBeromsu/devonthink-cl
 npm install -g @beomsukoh/zotero-cli
 ```
 
-## Quick Start
+Verify the installation:
 
 ```bash
-# List items (local Zotero API, no auth needed)
-zt items --limit 10
+zt items --limit 1
+```
 
-# Search
-zt search "machine learning"
+This prints a JSON array of items from your local Zotero library. If Zotero desktop is not running, the command exits with an error.
 
-# Get a specific item
-zt get ABCD1234
+## Quickstart
 
-# List collections
-zt collections
+List items in your library:
 
-# Export as BibTeX
-zt export --format bibtex
+```bash
+zt items --limit 10 --sort dateAdded
+```
 
-# Get item template for creating a journal article
-zt template journalArticle
+Search across your library:
 
-# Create an item
-zt create:item --type journalArticle --title "My Paper" --doi "10.1234/example"
+```bash
+zt search "attention is all you need"
+```
 
-# Attach a PDF to an item
-zt attach ./paper.pdf --key ABCD1234
+Get a specific item by key:
 
-# Get full-text content
-zt fulltext ABCD1234
+```bash
+zt get ABCD1234
+```
 
-# Show available item types
-zt types
+List collections:
 
-# Show fields for a specific type
-zt types journalArticle
+```bash
+zt collections
+```
 
-# Import paper by DOI (requires Translation Server)
-docker run -p 1969:1969 zotero/translation-server
+Import a paper by DOI (requires Translation Server):
+
+```bash
+docker run -d -p 1969:1969 zotero/translation-server
 zt import --doi "10.1145/3025453.3025912"
+```
 
-# Import from URL
-zt import --url "https://arxiv.org/abs/2301.01234"
+Attach a PDF to an existing item:
 
-# Import PDF: resolve DOI from filename, create item, attach PDF
-zt import ./10.1234_example.pdf
+```bash
+zt attach ./paper.pdf --key ABCD1234
 ```
 
-## Configuration
+Export your library as BibTeX:
 
-| Variable | Default | Description |
-|---|---|---|
-| `ZOTERO_BASE_URL` | `http://localhost:23119/api` | API base URL |
-| `ZOTERO_API_KEY` | — | API key (required for writes) |
-| `ZOTERO_USER_ID` | `0` | User ID (`0` = local API) |
-| `ZOTERO_TRANSLATION_SERVER` | `http://localhost:1969` | Translation Server URL (for `import`) |
-
-**Local mode** (reads only, Zotero desktop must be running):
 ```bash
-zt items --limit 10
+zt export --format bibtex
 ```
 
-**Web mode** (full CRUD):
+## Dual-Mode Architecture
+
+Zotero CLI supports two modes of operation:
+
+| Mode | Base URL | Auth | Capabilities |
+|---|---|---|---|
+| **Local** (default) | `http://localhost:23119/api` | None | Read-only; Zotero desktop must be running |
+| **Web** | `https://api.zotero.org` | API key | Full CRUD; works remotely |
+
+**Local mode** requires no configuration — just have Zotero desktop running.
+
+**Web mode** requires an API key from [zotero.org/settings/keys](https://www.zotero.org/settings/keys/):
+
 ```bash
 export ZOTERO_API_KEY=your_key_here
 export ZOTERO_USER_ID=12345
 export ZOTERO_BASE_URL=https://api.zotero.org
 ```
 
+### Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `ZOTERO_BASE_URL` | `http://localhost:23119/api` | API base URL |
+| `ZOTERO_API_KEY` | — | API key (required for writes) |
+| `ZOTERO_USER_ID` | `0` | User ID (`0` = local) |
+| `ZOTERO_TRANSLATION_SERVER` | `http://localhost:1969` | Translation Server URL |
+
 ## Commands
 
 ### Core
@@ -85,15 +113,15 @@ export ZOTERO_BASE_URL=https://api.zotero.org
 | Command | Description |
 |---|---|
 | `zt items` | List items (`--collection`, `--top`, `--tag`, `--type`, `--limit`, `--sort`) |
-| `zt collections` | List collections (`--parent`) |
-| `zt get <key>` | Get item by key (`--children` for child items) |
+| `zt collections` | List collections (`--parent` for subcollections) |
+| `zt get <key>` | Get item by key (`--children` for attachments/notes) |
 | `zt search <query>` | Search items (`--qmode`, `--tag`, `--type`) |
 | `zt tags` | List tags |
 | `zt libraries` | List group libraries |
 | `zt delete --key <key>` | Delete item or collection (`--collection` flag) |
-| `zt attach <file> --key <key>` | Attach file to item (`--content-type`) |
-| `zt export --format <fmt>` | Export items (bibtex, ris, csljson, csv, tei, etc.) |
-| `zt fulltext <key>` | Get full-text content |
+| `zt attach <file> --key <key>` | Upload and attach file to item |
+| `zt export --format <fmt>` | Export items in citation formats |
+| `zt fulltext <key>` | Get full-text content of an item |
 | `zt import` | Import from DOI, ISBN, arXiv, URL, BibTeX, or PDF |
 
 ### Create
@@ -107,22 +135,112 @@ export ZOTERO_BASE_URL=https://api.zotero.org
 
 | Command | Description |
 |---|---|
-| `zt types [itemType]` | List item types, or fields for a specific type |
-| `zt template <itemType>` | Get JSON template for creating items |
+| `zt types [itemType]` | List item types, or fields/creators for a type |
+| `zt template <itemType>` | Get JSON template for item creation |
+
+Run `zt --help` or `zt <command> --help` for full usage.
+
+## Examples
+
+### Import a paper by DOI and attach its PDF
+
+```bash
+# Start translation server (one-time)
+docker run -d -p 1969:1969 zotero/translation-server
+
+# Import: resolves metadata via Translation Server, creates item, attaches PDF
+zt import ./paper.pdf --doi "10.1145/3025453.3025912" --collection COLL1234
+```
+
+### Import from arXiv
+
+```bash
+zt import --arxiv "2301.01234"
+```
+
+### Import from a BibTeX file
+
+```bash
+zt import --bibtex ./references.bib
+```
+
+### Create a journal article manually
+
+```bash
+# Get the template first
+zt template journalArticle
+
+# Create with specific fields
+zt create:item --type journalArticle \
+  --title "My Research Paper" \
+  --doi "10.1234/example" \
+  --date "2026" \
+  --collection COLL1234
+```
+
+### Create from raw JSON
+
+```bash
+zt create:item '{"itemType":"book","title":"Clean Code","creators":[{"creatorType":"author","firstName":"Robert","lastName":"Martin"}]}'
+```
+
+### Browse item type schema
+
+```bash
+# List all 42 item types
+zt types
+
+# Show fields for journal articles
+zt types journalArticle
+
+# Show creator types for books
+zt types book --creators
+```
+
+### Export a collection as CSL-JSON
+
+```bash
+zt export --format csljson --collection ABCD1234
+```
 
 ### Export Formats
 
 `bibtex`, `biblatex`, `ris`, `csljson`, `csv`, `tei`, `wikipedia`, `mods`, `refer`
 
-## Architecture
+### Work with group libraries
+
+```bash
+# List groups
+zt libraries
+
+# List items in a group
+zt items --group 12345
+
+# Search within a group
+zt search "deep learning" --group 12345
+```
+
+## Philosophy
+
+`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.
 
+The `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.
+
+## Development
+
+```bash
+pnpm install
+pnpm check          # TypeScript + doc validation
+pnpm test           # Unit tests
+pnpm build
+pnpm pack:check     # Package integrity
 ```
-zt <command> [options]
-  -> CommandRegistry -> CommandModule.parse() -> CommandModule.execute()
-    -> ZoteroPort (application boundary)
-      -> HttpZoteroAdapter
-        -> Zotero Local API (localhost:23119) or Web API (api.zotero.org)
-        -> Translation Server (localhost:1969) for import
+
+## Publishing
+
+```bash
+pnpm release:check
+npm publish --access public
 ```
 
 ## License

package/dist/adapters/http/HttpZoteroAdapter.js

@@ -226,10 +226,69 @@ export class HttpZoteroAdapter {
         await this.parseResponse(registerResponse);
         return { success: true, key: attachmentKey };
     }
+    async downloadAttachment(library, itemKey) {
+        const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/file`);
+        const response = await this.http.requestRaw("GET", url, {
+            headers: this.headers(),
+        });
+        if (response.status === 404) {
+            throw new NotFoundError(`Attachment not found: ${itemKey}`);
+        }
+        if (response.status >= 400) {
+            throw new ExternalToolError(`Failed to download attachment (${response.status})`);
+        }
+        return response.data;
+    }
     async getFileUrl(library, itemKey) {
         const url = this.buildUrl(`${this.libraryPrefix(library)}/items/${itemKey}/file`);
         return url;
     }
+    // ── Reparent ────────────────────────────────────────────────────
+    async reparentItem(library, itemKey, newParentKey) {
+        const item = (await this.getItem(library, itemKey));
+        const version = item["version"] ?? 0;
+        return this.updateItem(library, itemKey, { parentItem: newParentKey }, version);
+    }
+    // ── Better BibTeX ───────────────────────────────────────────────
+    get bbtUrl() {
+        const base = this.baseUrl.replace(/\/api\/?$/, "");
+        return `${base}/better-bibtex/json-rpc`;
+    }
+    async bbtRpc(method, params) {
+        const response = await this.http.request("POST", this.bbtUrl, {
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
+        });
+        if (response.status >= 400) {
+            throw new ExternalToolError(`Better BibTeX RPC error (${response.status}): ${response.body}`);
+        }
+        const parsed = JSON.parse(response.body);
+        if (parsed["error"]) {
+            throw new ExternalToolError(`BBT error: ${JSON.stringify(parsed["error"])}`);
+        }
+        return parsed["result"] ?? null;
+    }
+    async bbtCiteKeys(itemKeys) {
+        return this.bbtRpc("item.citationkey", [itemKeys]);
+    }
+    async bbtExport(itemKeys, translator) {
+        const result = await this.bbtRpc("item.export", [itemKeys, translator]);
+        return String(result);
+    }
+    async bbtSearch(query) {
+        return this.bbtRpc("item.search", [query]);
+    }
+    async bbtProbe() {
+        try {
+            const base = this.baseUrl.replace(/\/api\/?$/, "");
+            const url = `${base}/better-bibtex/cayw?probe=true`;
+            const response = await this.http.request("GET", url, {});
+            return response.status === 200;
+        }
+        catch {
+            return false;
+        }
+    }
     // ── Translation Server methods ────────────────────────────────
     async resolveIdentifier(identifier) {
         const url = `${this.translationServerUrl}/search`;

package/dist/commands/bbtCommand.js

@@ -0,0 +1,85 @@
+import { ValidationError } from "../application/errors.js";
+import { assertNoMissingOptionValues, assertNoUnknownOptions, getOption, parseArgs } from "../utils/args.js";
+import { renderJson } from "./helpers.js";
+const VALID_SUBCOMMANDS = new Set(["status", "cite", "export", "search"]);
+export class BbtCommand {
+    name = "bbt";
+    category = "Lookup";
+    description = "Better BibTeX operations: cite keys, export, search, status.";
+    help() {
+        return [
+            "Usage:",
+            "  zt bbt status",
+            "  zt bbt cite <key> [<key>...]",
+            "  zt bbt export <key> [<key>...] --translator better-bibtex",
+            "  zt bbt search <query>",
+            "",
+            "Better BibTeX operations.",
+            "",
+            "Subcommands:",
+            "  status                 Check if BBT is available",
+            "  cite <key> [<key>...]  Get citation keys for items",
+            "  export <key> [...]     Export items via BBT",
+            "  search <query>         Search via BBT",
+            "",
+            "Options:",
+            "  --translator <name>    Translator for export (default: better-bibtex)",
+            "",
+            "Examples:",
+            "  zt bbt status",
+            "  zt bbt cite ABC12345 DEF67890",
+            "  zt bbt export ABC12345 --translator better-biblatex",
+            "  zt bbt search \"attention is all you need\""
+        ].join("\n");
+    }
+    parse(argv) {
+        const parsed = parseArgs(argv);
+        assertNoUnknownOptions(parsed, ["translator"]);
+        assertNoMissingOptionValues(parsed, ["translator"]);
+        const subcommand = parsed.positionals[0];
+        if (!subcommand) {
+            throw new ValidationError("bbt requires a subcommand: status, cite, export, search");
+        }
+        if (!VALID_SUBCOMMANDS.has(subcommand)) {
+            throw new ValidationError(`Unknown bbt subcommand: ${subcommand}. Valid: status, cite, export, search`);
+        }
+        const args = parsed.positionals.slice(1);
+        const translator = getOption(parsed, "translator") ?? "better-bibtex";
+        // Validate args per subcommand
+        if (subcommand === "cite" && args.length === 0) {
+            throw new ValidationError("bbt cite requires at least one item key.");
+        }
+        if (subcommand === "export" && args.length === 0) {
+            throw new ValidationError("bbt export requires at least one item key.");
+        }
+        if (subcommand === "search" && args.length === 0) {
+            throw new ValidationError("bbt search requires a query.");
+        }
+        return { subcommand: subcommand, args, translator };
+    }
+    async execute(input, context) {
+        switch (input.subcommand) {
+            case "status": {
+                const available = await context.zotero.bbtProbe();
+                context.output.write(renderJson({ available }));
+                break;
+            }
+            case "cite": {
+                const result = await context.zotero.bbtCiteKeys(input.args);
+                context.output.write(renderJson(result));
+                break;
+            }
+            case "export": {
+                const result = await context.zotero.bbtExport(input.args, input.translator);
+                context.output.write(result);
+                break;
+            }
+            case "search": {
+                const query = input.args.join(" ");
+                const result = await context.zotero.bbtSearch(query);
+                context.output.write(renderJson(result));
+                break;
+            }
+        }
+    }
+}

package/dist/commands/downloadCommand.js

@@ -0,0 +1,59 @@
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { ValidationError } from "../application/errors.js";
+import { assertNoMissingOptionValues, assertNoUnknownOptions, getOption, parseArgs } from "../utils/args.js";
+import { renderJson, resolveLibrary } from "./helpers.js";
+export class DownloadCommand {
+    name = "download";
+    category = "Core";
+    description = "Download an attachment file to disk.";
+    help() {
+        return [
+            "Usage:",
+            "  zt download <key>",
+            "  zt download <key> --output ./paper.pdf",
+            "",
+            "Download an attachment file to disk.",
+            "",
+            "Options:",
+            "  --group <id>           Library group ID",
+            "  --output <path>        Output file path (default: current dir + filename from item)",
+            "",
+            "Examples:",
+            "  zt download ABC12345",
+            "  zt download ABC12345 --output ./paper.pdf",
+            "  zt download ABC12345 --group 123456"
+        ].join("\n");
+    }
+    parse(argv, context) {
+        const parsed = parseArgs(argv);
+        assertNoUnknownOptions(parsed, ["group", "output"]);
+        assertNoMissingOptionValues(parsed, ["group", "output"]);
+        if (parsed.positionals.length > 1) {
+            throw new ValidationError("download accepts at most one positional argument (item key).");
+        }
+        const key = parsed.positionals[0];
+        if (!key) {
+            throw new ValidationError("download requires an item key. Usage: zt download <key>");
+        }
+        const library = resolveLibrary(parsed, context?.config ?? { baseUrl: "" });
+        const output = getOption(parsed, "output");
+        return { library, key, output };
+    }
+    async execute(input, context) {
+        // Get item metadata to determine filename if output path not specified
+        const item = await context.zotero.getItem(input.library, input.key);
+        const data = item.data;
+        const filename = data?.filename ?? `${input.key}`;
+        const outputPath = input.output
+            ? resolve(input.output)
+            : resolve(process.cwd(), filename);
+        const buffer = await context.zotero.downloadAttachment(input.library, input.key);
+        await writeFile(outputPath, buffer);
+        context.output.write(renderJson({
+            success: true,
+            path: outputPath,
+            size: buffer.length
+        }));
+    }
+}

package/dist/commands/reparentCommand.js

@@ -0,0 +1,45 @@
+import { ValidationError } from "../application/errors.js";
+import { assertNoMissingOptionValues, assertNoUnknownOptions, getOption, parseArgs } from "../utils/args.js";
+import { ensureNoPositionals, renderJson, resolveLibrary } from "./helpers.js";
+export class ReparentCommand {
+    name = "reparent";
+    category = "Core";
+    description = "Change the parent of an attachment or note item.";
+    help() {
+        return [
+            "Usage:",
+            "  zt reparent --key <attachmentKey> --parent <newParentKey>",
+            "",
+            "Change the parent of an attachment or note item.",
+            "",
+            "Options:",
+            "  --key <key>            Attachment or note key (required)",
+            "  --parent <key>         New parent item key (required)",
+            "  --group <id>           Library group ID",
+            "",
+            "Examples:",
+            "  zt reparent --key ATT12345 --parent ABC12345",
+            "  zt reparent --key ATT12345 --parent ABC12345 --group 123456"
+        ].join("\n");
+    }
+    parse(argv, context) {
+        const parsed = parseArgs(argv);
+        assertNoUnknownOptions(parsed, ["key", "parent", "group"]);
+        assertNoMissingOptionValues(parsed, ["key", "parent", "group"]);
+        ensureNoPositionals(parsed, "reparent");
+        const key = getOption(parsed, "key");
+        if (!key) {
+            throw new ValidationError("reparent requires --key <attachmentKey>.");
+        }
+        const parentKey = getOption(parsed, "parent");
+        if (!parentKey) {
+            throw new ValidationError("reparent requires --parent <newParentKey>.");
+        }
+        const library = resolveLibrary(parsed, context?.config ?? { baseUrl: "" });
+        return { library, key, parentKey };
+    }
+    async execute(input, context) {
+        const result = await context.zotero.reparentItem(input.library, input.key, input.parentKey);
+        context.output.write(renderJson(result));
+    }
+}

package/dist/compositionRoot.js

@@ -17,6 +17,9 @@ import { FulltextCommand } from "./commands/fulltextCommand.js";
 import { TemplateCommand } from "./commands/templateCommand.js";
 import { TypesInfoCommand } from "./commands/typesInfoCommand.js";
 import { ImportCommand } from "./commands/importCommand.js";
+import { DownloadCommand } from "./commands/downloadCommand.js";
+import { ReparentCommand } from "./commands/reparentCommand.js";
+import { BbtCommand } from "./commands/bbtCommand.js";
 export function createRuntime() {
     const config = {
         apiKey: process.env["ZOTERO_API_KEY"],
@@ -43,5 +46,8 @@ export function createRuntime() {
     registry.register(new TemplateCommand());
     registry.register(new TypesInfoCommand());
     registry.register(new ImportCommand());
+    registry.register(new DownloadCommand());
+    registry.register(new ReparentCommand());
+    registry.register(new BbtCommand());
     return { output, zotero, registry, config };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beomsukoh/zotero-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pure CLI wrapper for the Zotero API.",
   "type": "module",
   "bin": {