junghan0611/bibcli

bibcli — local search + Zotero companion workflow

Binary: {baseDir}/bibcli
Agent default: use explicit --dir ~/org/resources.

1) Core bibcli (read-only, local BibTeX)

| Need | Command | Notes | |---|---|---| | Search existing entries | {baseDir}/bibcli search "query words" --dir ~/org/resources --max 10 | AND search over citation key, title, author, keywords, date, abstract | | Show one entry | {baseDir}/bibcli show "citation-key" --dir ~/org/resources | Full JSON incl. url / isbn / abstract / keywords | | List by type | {baseDir}/bibcli list --type Book --dir ~/org/resources --max 20 | Types: Book, Online, Software, Reference, Video, Article, Misc | | Library stats | {baseDir}/bibcli stats --dir ~/org/resources | Sanity check local bib files | | Lookup book metadata | {baseDir}/bibcli lookup 9791192300283 | data4library only; needs DATA4LIBRARY_API_KEY |

2) zotero-config companion workflow (writes to Zotero)

Use this path when the note has a source URL but no citation key yet. Preferred: one shot with save --sync --json — it saves, runs bib sync, and returns the resolved citationKey deterministically. No title-grepping.

cd ~/repos/gh/zotero-config
./run.sh server status || ./run.sh server start
./run.sh save --sync --json "https://example.com/article"
# => { saved:[...], resolved:[{zoteroKey, citationKey, title, url, ...}] }

Take resolved[].citationKey and drop it straight into the note. Optionally verify: {baseDir}/bibcli show "citation-key" --dir ~/org/resources.

Fallback (when --sync --json is unavailable)

| Step | Command | |---|---| | Save URL | cd ~/repos/gh/zotero-config && ./run.sh save "https://example.com/article" | | Sync BibTeX | cd ~/repos/gh/zotero-config && ./run.sh bib sync | | Recover key | {baseDir}/bibcli search "distinctive title author words" --dir ~/org/resources --max 5 | | Verify | {baseDir}/bibcli show "citation-key" --dir ~/org/resources |

Decision rule

• Have citation key → show
• Need an existing local source → search
• Only have URL and the source should enter Zotero → save --sync --json, then use resolved[].citationKey
• Do not leave #+print_bibliography: orphaned when one save --sync --json can fix it

Practical bib-note pattern

cd ~/repos/gh/zotero-config
./run.sh server status || ./run.sh server start
./run.sh save --sync --json "https://example.com/article"
# read resolved[].citationKey from the JSON output

Then add:

#+reference: citation-key
#+print_bibliography:

Important notes

• save mutates Zotero Cloud. Use it only when the source belongs in the library.
• Plain save returns Zotero item keys, not citation keys — prefer save --sync --json, which resolves the citation key for you.
• bibcli search does not currently match raw url; search by title / author / keywords after sync.
• lookup helps book / ISBN workflows, but writes nothing to Zotero.
• If server start fails, expected repo: ~/repos/3rd/translation-server.

Environment

| Variable | Used by | Purpose | |---|---|---| | BIBCLI_DIR | bibcli | Default BibTeX directory | | DATA4LIBRARY_API_KEY | lookup | Book metadata / KDC lookup | | ZOTERO_API_KEY | ./run.sh save, ./run.sh bib * | Zotero Web API | | ZOTERO_USER_ID | ./run.sh save, ./run.sh bib * | Zotero user/library | | ZOTERO_TRANSLATION_SERVER | ./run.sh save | Default: http://localhost:1969 |

Output

All bibcli output is JSON.

• search / list: brief entries
• show: full flattened entry
• stats: counts per bib file
• lookup: data4library candidates