bibcite-cli 0.5.4__tar.gz → 0.6.0__tar.gz

bibcite_cli-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Run tests
+        run: uv run --frozen pytest -q
+
+  quality:
+    name: Lint and build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Run Ruff
+        run: uv run --frozen ruff check .
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test the wheel
+        run: uvx --from dist/*.whl bibcite --help

bibcite_cli-0.6.0/.github/workflows/publish.yml

@@ -0,0 +1,74 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the release
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Verify the release tag matches the package version
+        run: |
+          package_version="$(uv version --short)"
+          if [ "${GITHUB_REF_NAME}" != "v${package_version}" ]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match package version ${package_version}."
+            exit 1
+          fi
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-groups
+
+      - name: Run tests
+        run: uv run --frozen pytest -q
+
+      - name: Run Ruff
+        run: uv run --frozen ruff check .
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Smoke-test the wheel
+        run: uvx --from dist/*.whl bibcite --help
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Upload release to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bibcite-cli
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

bibcite_cli-0.6.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: bibcite-cli
+Version: 0.6.0
+Summary: Resolve papers (arXiv id / DOI / title) to canonical, normalized BibTeX for agents and humans
+Project-URL: Repository, https://github.com/leo1oel/bibcite
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arxiv,bibliography,bibtex,citations,dblp
+Requires-Python: >=3.10
+Requires-Dist: bibtexparser<2,>=1.4
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/bibcite.svg" width="128" alt="bibcite logo">
+</p>
+
+<h1 align="center">bibcite</h1>
+
+<p align="center">
+  Turn an arXiv ID, DOI, or paper title into clean BibTeX, then keep the whole bibliography normalized and deduplicated.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bibcite-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/bibcite-cli?color=6366f1"></a>
+  <a href="https://pypi.org/project/bibcite-cli/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/bibcite-cli"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/leo1oel/bibcite"></a>
+</p>
+
+`bibcite` resolves a paper to its published record when one exists, preserves arXiv links, canonicalizes venue names, and writes the result into a `.bib` file without breaking existing citation keys.
+It is built for both terminal use and coding agents that need a dependable alternative to editing BibTeX by hand.
+
+## Quick start with an agent
+
+Install the bundled skill so your coding agent knows how to manage citations with `bibcite`:
+
+```bash
+npx -y skills add leo1oel/bibcite --skill bibcite --global --yes
+```
+
+Install the CLI once as well, or let the agent install it on the first bibliography task:
+
+```bash
+uv tool install bibcite-cli
+```
+
+You can then ask your agent to handle the bibliography in plain language:
+
+```text
+Add arXiv:1706.03762 to references.bib and cite it in main.tex.
+Upgrade the arXiv entries in references.bib to their published versions.
+Check and fix references.bib before submission.
+```
+
+The skill tells the agent to call `bibcite` for every `.bib` change, read the citation key from its JSON output, and use that exact key in `\cite{...}`.
+The agent never needs to guess a key or edit a BibTeX entry by hand.
+
+## Use the CLI directly
+
+Install the command from PyPI if you have not already done so:
+
+```bash
+uv tool install bibcite-cli
+```
+
+Resolve a paper and add it to your bibliography:
+
+```bash
+bibcite add references.bib 1706.03762
+```
+
+The command prints a machine-readable result, including the stable citation key:
+
+```json
+{
+  "query": "1706.03762",
+  "action": "added",
+  "key": "vaswani2017attention",
+  "title": "Attention is All you Need",
+  "venue": "Advances in Neural Information Processing Systems (NIPS)",
+  "published": true,
+  "source": "semanticscholar",
+  "file": "references.bib",
+  "tidied": true
+}
+```
+
+You can now cite it as `\cite{vaswani2017attention}`.
+Running the same command again is safe: `bibcite` detects the existing entry and does not add a duplicate.
+
+When `add` writes a new entry, it runs [bibtex-tidy](https://github.com/FlamingTempura/bibtex-tidy) automatically unless you pass `--no-tidy`.
+It uses a globally installed `bibtex-tidy` command when available and otherwise runs it through `npx --yes bibtex-tidy`.
+`npx` downloads the formatter automatically on first use, so the agent-first setup does not require a separate `bibtex-tidy` installation.
+The JSON result reports `"tidied": true` when formatting succeeds.
+
+If neither `bibtex-tidy` nor `npx` is available, or if the formatter fails, the entry remains written but the command exits with code `1` and reports `"tidied": false`.
+An `"action": "exists"` result also reports `"tidied": false` because no file change occurred, so `add` skips the formatting pass.
+Run `bibcite tidy references.bib` or `bibcite fix references.bib` when you want to format an existing file.
+
+You can also try a one-off command without installing `bibcite`:
+
+```bash
+uvx --from bibcite-cli bibcite get "Attention is all you need"
+```
+
+## What it handles
+
+- It accepts arXiv IDs and URLs, arXiv DOIs such as `10.48550/arXiv.1706.03762`, standard DOIs, and paper titles.
+- It searches for a published version before falling back to an arXiv preprint, and it reports when source outages make that check incomplete.
+- It canonicalizes journal, conference, and workshop names against the bundled venue table, including year-sensitive names such as NIPS and NeurIPS.
+- It assigns the correct BibTeX entry type and field, such as `@inproceedings` with `booktitle` or `@article` with `journal`.
+- It deduplicates by arXiv ID, DOI, exact title, and similar titles from the same first author.
+- It upgrades preprints in place while preserving citation keys already used by your LaTeX source.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `bibcite get <query>` | Preview resolved BibTeX without writing a file. |
+| `bibcite add <file> <query>` | Resolve, deduplicate, add, and tidy an entry. |
+| `bibcite add <file> --bibtex "..."` | Normalize and add a raw BibTeX entry. |
+| `bibcite add <file> --from ids.txt` | Add one query per line and tidy once at the end. |
+| `bibcite upgrade <file>` | Replace arXiv entries with published records when available. |
+| `bibcite check <file>` | Find missing fields, duplicates, preprints, and all-caps author names without changing the file. |
+| `bibcite tidy <file>` | Apply the canonical `bibtex-tidy` formatting rules. |
+| `bibcite fix <file>` | Upgrade preprints, tidy the file, and run the checks in one command. |
+| `bibcite remove <file> <key>` | Remove an entry by citation key. |
+
+### Common workflows
+
+Preview a result as BibTeX or JSON:
+
+```bash
+bibcite get 1706.03762
+bibcite get 10.1109/CVPR52688.2022.01167 --json
+```
+
+Add raw BibTeX from the clipboard:
+
+```bash
+pbpaste | bibcite add references.bib --bibtex -
+```
+
+Replace a bad entry while keeping its current key:
+
+```bash
+bibcite add references.bib "correct paper title" --key existingKey
+```
+
+Check what would be upgraded without writing the file:
+
+```bash
+bibcite upgrade references.bib --dry-run
+```
+
+Mark a confirmed preprint-only entry with `pubstate = {preprint}` if you want `check` and `upgrade` to leave it alone.
+
+## How resolution works
+
+For arXiv IDs and titles, `bibcite` collects paper metadata and checks publication sources in a cascade derived from [PaperMemory](https://github.com/vict0rsch/PaperMemory): DBLP, Semantic Scholar, Google Scholar, Crossref, Unpaywall, and OpenAlex.
+A published match must have the same normalized title or pass a guarded title-drift check, have a plausible publication year, and name a non-preprint venue.
+
+Successful published matches are cached at `~/.cache/bibcite/published.json`.
+Preprint-only results are never cached because a paper may be published later.
+Use `--no-cache` or set `BIBCITE_NO_CACHE=1` to bypass the cache.
+
+## Configuration
+
+Set `BIBCITE_STRINGS=/path/to/strings.bib` to use your own venue table, or place one at `~/.config/bibcite/strings.bib`.
+
+These optional environment variables improve source reliability:
+
+| Variable | Effect |
+| --- | --- |
+| `OPENALEX_API_KEY` | Uses your OpenAlex quota instead of the anonymous shared pool. |
+| `S2_API_KEY` | Uses a private Semantic Scholar quota. |
+| `BIBCITE_MAILTO` | Sends your contact email to the Crossref, OpenAlex, and Unpaywall polite pools. |
+| `BIBCITE_CORE_SOURCES` | Overrides the sources required for a trustworthy publication check. |
+| `BIBCITE_NO_CACHE=1` | Disables the local publication cache. |
+
+## Exit codes and agent use
+
+`add`, `remove`, `upgrade`, `check`, and `fix` print JSON on standard output and send diagnostics to standard error.
+This keeps their output easy to parse from scripts and agents.
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The command completed successfully. |
+| `1` | A file, lint, or formatting problem remains. |
+| `2` | The paper or requested entry could not be found. |
+| `3` | Publication sources or an internal tool failed. |
+
+Agents should call `bibcite add <file> <query>` and use the returned `key` in `\cite{...}`.
+They should never modify `.bib` entries directly because doing so bypasses deduplication, venue normalization, and stable-key handling.
+
+## Development
+
+```bash
+git clone https://github.com/leo1oel/bibcite.git
+cd bibcite
+uv sync --all-groups
+uv run pytest
+```
+
+Install the checkout as an editable command while developing:
+
+```bash
+uv tool install --editable .
+```
+
+## License
+
+`bibcite` is available under the [MIT License](LICENSE).

bibcite_cli-0.6.0/Readme.md

@@ -0,0 +1,200 @@
+<p align="center">
+  <img src="assets/bibcite.svg" width="128" alt="bibcite logo">
+</p>
+
+<h1 align="center">bibcite</h1>
+
+<p align="center">
+  Turn an arXiv ID, DOI, or paper title into clean BibTeX, then keep the whole bibliography normalized and deduplicated.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/bibcite-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/bibcite-cli?color=6366f1"></a>
+  <a href="https://pypi.org/project/bibcite-cli/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/bibcite-cli"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/leo1oel/bibcite"></a>
+</p>
+
+`bibcite` resolves a paper to its published record when one exists, preserves arXiv links, canonicalizes venue names, and writes the result into a `.bib` file without breaking existing citation keys.
+It is built for both terminal use and coding agents that need a dependable alternative to editing BibTeX by hand.
+
+## Quick start with an agent
+
+Install the bundled skill so your coding agent knows how to manage citations with `bibcite`:
+
+```bash
+npx -y skills add leo1oel/bibcite --skill bibcite --global --yes
+```
+
+Install the CLI once as well, or let the agent install it on the first bibliography task:
+
+```bash
+uv tool install bibcite-cli
+```
+
+You can then ask your agent to handle the bibliography in plain language:
+
+```text
+Add arXiv:1706.03762 to references.bib and cite it in main.tex.
+Upgrade the arXiv entries in references.bib to their published versions.
+Check and fix references.bib before submission.
+```
+
+The skill tells the agent to call `bibcite` for every `.bib` change, read the citation key from its JSON output, and use that exact key in `\cite{...}`.
+The agent never needs to guess a key or edit a BibTeX entry by hand.
+
+## Use the CLI directly
+
+Install the command from PyPI if you have not already done so:
+
+```bash
+uv tool install bibcite-cli
+```
+
+Resolve a paper and add it to your bibliography:
+
+```bash
+bibcite add references.bib 1706.03762
+```
+
+The command prints a machine-readable result, including the stable citation key:
+
+```json
+{
+  "query": "1706.03762",
+  "action": "added",
+  "key": "vaswani2017attention",
+  "title": "Attention is All you Need",
+  "venue": "Advances in Neural Information Processing Systems (NIPS)",
+  "published": true,
+  "source": "semanticscholar",
+  "file": "references.bib",
+  "tidied": true
+}
+```
+
+You can now cite it as `\cite{vaswani2017attention}`.
+Running the same command again is safe: `bibcite` detects the existing entry and does not add a duplicate.
+
+When `add` writes a new entry, it runs [bibtex-tidy](https://github.com/FlamingTempura/bibtex-tidy) automatically unless you pass `--no-tidy`.
+It uses a globally installed `bibtex-tidy` command when available and otherwise runs it through `npx --yes bibtex-tidy`.
+`npx` downloads the formatter automatically on first use, so the agent-first setup does not require a separate `bibtex-tidy` installation.
+The JSON result reports `"tidied": true` when formatting succeeds.
+
+If neither `bibtex-tidy` nor `npx` is available, or if the formatter fails, the entry remains written but the command exits with code `1` and reports `"tidied": false`.
+An `"action": "exists"` result also reports `"tidied": false` because no file change occurred, so `add` skips the formatting pass.
+Run `bibcite tidy references.bib` or `bibcite fix references.bib` when you want to format an existing file.
+
+You can also try a one-off command without installing `bibcite`:
+
+```bash
+uvx --from bibcite-cli bibcite get "Attention is all you need"
+```
+
+## What it handles
+
+- It accepts arXiv IDs and URLs, arXiv DOIs such as `10.48550/arXiv.1706.03762`, standard DOIs, and paper titles.
+- It searches for a published version before falling back to an arXiv preprint, and it reports when source outages make that check incomplete.
+- It canonicalizes journal, conference, and workshop names against the bundled venue table, including year-sensitive names such as NIPS and NeurIPS.
+- It assigns the correct BibTeX entry type and field, such as `@inproceedings` with `booktitle` or `@article` with `journal`.
+- It deduplicates by arXiv ID, DOI, exact title, and similar titles from the same first author.
+- It upgrades preprints in place while preserving citation keys already used by your LaTeX source.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `bibcite get <query>` | Preview resolved BibTeX without writing a file. |
+| `bibcite add <file> <query>` | Resolve, deduplicate, add, and tidy an entry. |
+| `bibcite add <file> --bibtex "..."` | Normalize and add a raw BibTeX entry. |
+| `bibcite add <file> --from ids.txt` | Add one query per line and tidy once at the end. |
+| `bibcite upgrade <file>` | Replace arXiv entries with published records when available. |
+| `bibcite check <file>` | Find missing fields, duplicates, preprints, and all-caps author names without changing the file. |
+| `bibcite tidy <file>` | Apply the canonical `bibtex-tidy` formatting rules. |
+| `bibcite fix <file>` | Upgrade preprints, tidy the file, and run the checks in one command. |
+| `bibcite remove <file> <key>` | Remove an entry by citation key. |
+
+### Common workflows
+
+Preview a result as BibTeX or JSON:
+
+```bash
+bibcite get 1706.03762
+bibcite get 10.1109/CVPR52688.2022.01167 --json
+```
+
+Add raw BibTeX from the clipboard:
+
+```bash
+pbpaste | bibcite add references.bib --bibtex -
+```
+
+Replace a bad entry while keeping its current key:
+
+```bash
+bibcite add references.bib "correct paper title" --key existingKey
+```
+
+Check what would be upgraded without writing the file:
+
+```bash
+bibcite upgrade references.bib --dry-run
+```
+
+Mark a confirmed preprint-only entry with `pubstate = {preprint}` if you want `check` and `upgrade` to leave it alone.
+
+## How resolution works
+
+For arXiv IDs and titles, `bibcite` collects paper metadata and checks publication sources in a cascade derived from [PaperMemory](https://github.com/vict0rsch/PaperMemory): DBLP, Semantic Scholar, Google Scholar, Crossref, Unpaywall, and OpenAlex.
+A published match must have the same normalized title or pass a guarded title-drift check, have a plausible publication year, and name a non-preprint venue.
+
+Successful published matches are cached at `~/.cache/bibcite/published.json`.
+Preprint-only results are never cached because a paper may be published later.
+Use `--no-cache` or set `BIBCITE_NO_CACHE=1` to bypass the cache.
+
+## Configuration
+
+Set `BIBCITE_STRINGS=/path/to/strings.bib` to use your own venue table, or place one at `~/.config/bibcite/strings.bib`.
+
+These optional environment variables improve source reliability:
+
+| Variable | Effect |
+| --- | --- |
+| `OPENALEX_API_KEY` | Uses your OpenAlex quota instead of the anonymous shared pool. |
+| `S2_API_KEY` | Uses a private Semantic Scholar quota. |
+| `BIBCITE_MAILTO` | Sends your contact email to the Crossref, OpenAlex, and Unpaywall polite pools. |
+| `BIBCITE_CORE_SOURCES` | Overrides the sources required for a trustworthy publication check. |
+| `BIBCITE_NO_CACHE=1` | Disables the local publication cache. |
+
+## Exit codes and agent use
+
+`add`, `remove`, `upgrade`, `check`, and `fix` print JSON on standard output and send diagnostics to standard error.
+This keeps their output easy to parse from scripts and agents.
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The command completed successfully. |
+| `1` | A file, lint, or formatting problem remains. |
+| `2` | The paper or requested entry could not be found. |
+| `3` | Publication sources or an internal tool failed. |
+
+Agents should call `bibcite add <file> <query>` and use the returned `key` in `\cite{...}`.
+They should never modify `.bib` entries directly because doing so bypasses deduplication, venue normalization, and stable-key handling.
+
+## Development
+
+```bash
+git clone https://github.com/leo1oel/bibcite.git
+cd bibcite
+uv sync --all-groups
+uv run pytest
+```
+
+Install the checkout as an editable command while developing:
+
+```bash
+uv tool install --editable .
+```
+
+## License
+
+`bibcite` is available under the [MIT License](LICENSE).

bibcite_cli-0.6.0/assets/bibcite.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title description">
+  <title id="title">bibcite logo</title>
+  <desc id="description">A paper with citation marks and a verification check.</desc>
+  <defs>
+    <linearGradient id="background" x1="32" y1="24" x2="224" y2="232" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#6366F1"/>
+      <stop offset="1" stop-color="#7C3AED"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%">
+      <feDropShadow dx="0" dy="8" stdDeviation="8" flood-color="#312E81" flood-opacity="0.28"/>
+    </filter>
+  </defs>
+  <rect width="256" height="256" rx="56" fill="url(#background)"/>
+  <path d="M67 48h89l37 37v116c0 9.4-7.6 17-17 17H67c-9.4 0-17-7.6-17-17V65c0-9.4 7.6-17 17-17Z" fill="#FFFFFF" filter="url(#shadow)"/>
+  <path d="M156 48v28c0 9.4 7.6 17 17 17h20" fill="#E0E7FF"/>
+  <path d="m156 48 37 37h-28c-5 0-9-4-9-9V48Z" fill="#C7D2FE"/>
+  <path d="M81 112c-8 4-12 11-12 22v18h22v-20H80c0-5 3-9 9-12l-8-8Zm40 0c-8 4-12 11-12 22v18h22v-20h-11c0-5 3-9 9-12l-8-8Z" fill="#6366F1"/>
+  <rect x="70" y="172" width="69" height="10" rx="5" fill="#CBD5E1"/>
+  <circle cx="181" cy="184" r="35" fill="#14B8A6" stroke="#FFFFFF" stroke-width="8"/>
+  <path d="m165 184 11 11 22-25" fill="none" stroke="#FFFFFF" stroke-width="9" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

{bibcite_cli-0.5.4 → bibcite_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bibcite-cli"
-version = "0.5.4"
+version = "0.6.0"
 description = "Resolve papers (arXiv id / DOI / title) to canonical, normalized BibTeX for agents and humans"
 readme = "Readme.md"
 license = "MIT"
@@ -20,6 +20,7 @@ bibcite = "bibcite.cli:main"
 [dependency-groups]
 dev = [
     "pytest>=8",
+    "ruff>=0.15,<0.16",
 ]
 
 [build-system]

bibcite_cli-0.6.0/skills/bibcite/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: bibcite
+description: Manage paper citations and .bib files through the bibcite CLI instead of hand-editing them. Use whenever a task involves adding a paper reference or \cite, resolving an arXiv ID, arXiv DOI, DOI, or title to BibTeX, cleaning or checking a bibliography, deduplicating entries, or upgrading arXiv preprints to published records.
+compatibility: Requires bibcite or uv, network access for paper resolution, and Node.js with npx for automatic formatting.
+---
+
+# bibcite
+
+Route every `.bib` change through `bibcite` because the CLI resolves metadata, canonicalizes venues, deduplicates entries, preserves existing citation keys, and formats the file.
+Never add, replace, or delete a `.bib` entry by editing the file directly.
+
+If `bibcite` is not on `PATH`, install it with `uv tool install bibcite-cli`, then use the commands below.
+
+## Choose the command
+
+```bash
+bibcite add refs.bib <arXiv ID | arXiv URL | arXiv DOI | DOI | title>
+bibcite add refs.bib --bibtex '<complete BibTeX entry>'
+bibcite add refs.bib --from queries.txt
+bibcite add refs.bib <query> --replace
+bibcite add refs.bib <query> --key existingKey
+bibcite remove refs.bib <key>
+bibcite get <query> [--json]
+bibcite upgrade refs.bib [--dry-run]
+bibcite check refs.bib
+bibcite tidy refs.bib
+bibcite fix refs.bib
+```
+
+Use `get` only to preview a paper without changing a bibliography.
+Use `add` for one paper, and pass an arXiv ID, an arXiv DOI such as `10.48550/arXiv.1706.03762`, a standard DOI, or an exact title.
+Use `--from` for multiple papers because one process shares source throttling state and tidies the file once.
+Use `--replace` only when the resolved paper should overwrite an automatically matched entry.
+Use `--key` when title drift prevents automatic matching and a specific existing citation key must be replaced.
+Use `upgrade --dry-run` before upgrading a large bibliography.
+Use `fix` when the user asks to clean up a bibliography end to end.
+
+## Use the returned citation key
+
+File-changing commands print a JSON result on standard output and diagnostics on standard error.
+Read the `key` from JSON after `add` and use that exact value in `\cite{...}` instead of guessing or reconstructing it.
+After a write, confirm that `tidied` is `true` before reporting that formatting completed.
+An `exists` result may have `tidied` set to `false` because the file was unchanged, so `add` skipped the formatting pass.
+For any other `tidied: false` result, expect exit code `1` and retry once with `bibcite tidy <file>`.
+`bibcite` downloads `bibtex-tidy` through `npx`, so do not install it separately.
+If Node.js or `npx` is missing, ask before installing it and never format the file by hand.
+
+Treat these `action` values as successful outcomes:
+
+- `added` means a new entry was written.
+- `exists` means the paper was already present and no duplicate was added.
+- `upgraded` means a preprint was replaced by its published record while keeping the existing key.
+- `replaced` means an explicitly targeted entry was overwritten while keeping its existing key.
+
+For batch commands, inspect every item in `results` because one failed query does not invalidate successful entries.
+
+## Handle publication uncertainty
+
+An unmatched upgrade reports either `no_published_version` or `sources_unavailable`.
+Treat `no_published_version` as a trustworthy miss.
+Treat `sources_unavailable` as temporary because rate limits or outages prevented a complete check, so retry later without writing a replacement by hand.
+
+A preprint result may include `published_check`.
+Treat `complete` as a trustworthy publication check and `incomplete` as a reason to retry later.
+
+An entry that is intentionally preprint-only can use `pubstate = {preprint}` to mute future `check` and `upgrade` warnings.
+Submit the complete updated entry through `--bibtex` and target its existing key rather than editing the file directly.
+
+## Handle exit codes
+
+- Exit code `0` means the command completed successfully.
+- Exit code `1` means a file, lint, or formatting problem remains.
+  Inspect `problems`, `remaining_problems`, and `tidied` before deciding what to do next.
+- Exit code `2` means the paper or requested entry was not found.
+  Ask for a stronger identifier, preferably an arXiv ID or DOI, instead of fabricating an entry.
+- Exit code `3` means publication sources or an internal tool failed.
+  Retry later and never fall back to hand-editing the bibliography.
+
+`check` is read-only, but it returns exit code `1` when it finds problems.
+`fix` also returns exit code `1` when unresolved lint issues remain or formatting fails.

{bibcite_cli-0.5.4 → bibcite_cli-0.6.0}/src/bibcite/__init__.py

@@ -1,3 +1,3 @@
 """bibcite: canonical BibTeX resolution for papers (arXiv id / DOI / title)."""
 
-__version__ = "0.5.4"
+__version__ = "0.6.0"