zotcli 0.2.1__tar.gz → 0.2.2__tar.gz

{zotcli-0.2.1 → zotcli-0.2.2}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.2] — 2026-05-19
+
+### Added
+
+- **`zot items fulltext`** — retrieve item full text with a tiered fallback strategy: direct network access (DOI/URL) → configured library credentials → Playwright interactive auth → local Zotero fulltext index → metadata fallback (title/abstract/notes). Supports `--offline`, `--playwright-auth/--no-playwright-auth`, `--max-chars`.
+- **`zot config library-auth`** — store or display per-library institution/username/password credentials used by `zot items fulltext` for paywalled retrieval. Credentials persist under `[library_auth.<id>]` in `config.toml`.
+- **Fulltext search** — `zot search "query" --fulltext` searches against the local Zotero fulltext index.
+
+### Fixed
+
+- **`save_config` crashed on `None` values** — when calling `tomli_w.dump`, `None` defaults (e.g. `database.path = None`) raised `TypeError: Object of type 'NoneType' is not TOML serializable`. Now strips `None` entries before serialising.
+
+### Merged
+
+- Combined `feat/write-capability` (M1–M6 write subsystem) with PR #1 (network-first fulltext retrieval) onto a single linear history on `master`.
+
+## [0.2.1] — 2026-05-17
+
+### Added
+
+- **`zot collections assign`** — assign an existing item to a collection. Writes a single row to the `collectionItems` join table (no sync-critical metadata involved; safe while Zotero is open).
+- **Collection membership check** — `zot collections show` now indicates whether a given item belongs to the collection.
+
+### Fixed
+
+- `updateSession` payload — connector requires `target` as a flat string, not a wrapped object; saveItems calls with an empty body no longer fail.
+
 ## [0.2.0] — 2026-05-10
 
 ### Added

{zotcli-0.2.1 → zotcli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zotcli
-Version: 0.2.1
+Version: 0.2.2
 Summary: A CLI for browsing, exporting, and adding items to a Zotero library
 Author-email: MohamedNumair <mo7amednumair@gmail.com>
 License: MIT
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 # zotcli (`zot`)
 ![alt text](zot.png)
 
-A command-line interface for your local [Zotero](https://www.zotero.org/) library. **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
+A "crazy" good command-line interface for your local [Zotero](https://www.zotero.org/) library. Queries `zotero.sqlite` directly — no Zotero app running and no API key required for reads. **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
 
 **Library stats on this machine:** 3,771 items · 200 collections · 3,201 tags · 6.2 GB storage
 
@@ -395,6 +395,22 @@ zot attachments open 5UFZMSLU
 
 ---
 
+### `zot items fulltext` — retrieve full text
+
+```bash
+zot items fulltext 5UFZMSLU
+zot items fulltext 5UFZMSLU --offline
+```
+
+Retrieval order:
+1. direct network access from DOI/URL (institution/network-location access),
+2. configured credentials (`zot config library-auth`),
+3. Playwright interactive login fallback,
+4. local Zotero fulltext index,
+5. metadata fallback (title/abstract/notes).
+
+---
+
 ### `zot export` — export to files
 
 **BibTeX:**
@@ -542,6 +558,11 @@ Self-contained config at `<zotcli-home>/config.toml`. Run `zot config path` to f
 [database]
 path = ""                        # empty = auto-detect zotero.sqlite
 
+[output]
+default_format = "table"
+color = true
+page_size = 50
+
 [write]
 enabled = false                  # opt-in; set true once with: zot config set write.enabled true
 connector_url = "http://127.0.0.1:23119"
@@ -553,6 +574,11 @@ email = ""
 
 [browser]
 headless = false                 # SSO/captcha needs headed browser
+
+[library_auth.1]
+institution = "KU Leuven"
+username = "alice"
+password = "token"
 ```
 
 Override `<zotcli-home>` with the `ZOTCLI_HOME` environment variable.
@@ -563,6 +589,7 @@ Override `<zotcli-home>` with the `ZOTCLI_HOME` environment variable.
 
 - Database opened with `sqlite3://…?mode=ro` — the OS-level read-only URI flag makes direct writes impossible
 - WAL journal detection warns if Zotero is currently open (pending writes may not be visible yet)
+- Network retrieval is optional and only used by `zot items fulltext` unless `--offline` is passed
 - Write operations route through Zotero's own connector HTTP server — never via direct SQLite mutation
 - Default is read-only; writes require explicit opt-in (`zot config set write.enabled true`)
 - No Zotero API key required

{zotcli-0.2.1 → zotcli-0.2.2}/README.md

@@ -1,7 +1,7 @@
 # zotcli (`zot`)
 ![alt text](zot.png)
 
-A command-line interface for your local [Zotero](https://www.zotero.org/) library. **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
+A "crazy" good command-line interface for your local [Zotero](https://www.zotero.org/) library. Queries `zotero.sqlite` directly — no Zotero app running and no API key required for reads. **Default: strictly read-only.** Write capabilities are opt-in and route through Zotero's own connector HTTP server — `zotero.sqlite` is **never** modified directly.
 
 **Library stats on this machine:** 3,771 items · 200 collections · 3,201 tags · 6.2 GB storage
 
@@ -363,6 +363,22 @@ zot attachments open 5UFZMSLU
 
 ---
 
+### `zot items fulltext` — retrieve full text
+
+```bash
+zot items fulltext 5UFZMSLU
+zot items fulltext 5UFZMSLU --offline
+```
+
+Retrieval order:
+1. direct network access from DOI/URL (institution/network-location access),
+2. configured credentials (`zot config library-auth`),
+3. Playwright interactive login fallback,
+4. local Zotero fulltext index,
+5. metadata fallback (title/abstract/notes).
+
+---
+
 ### `zot export` — export to files
 
 **BibTeX:**
@@ -510,6 +526,11 @@ Self-contained config at `<zotcli-home>/config.toml`. Run `zot config path` to f
 [database]
 path = ""                        # empty = auto-detect zotero.sqlite
 
+[output]
+default_format = "table"
+color = true
+page_size = 50
+
 [write]
 enabled = false                  # opt-in; set true once with: zot config set write.enabled true
 connector_url = "http://127.0.0.1:23119"
@@ -521,6 +542,11 @@ email = ""
 
 [browser]
 headless = false                 # SSO/captcha needs headed browser
+
+[library_auth.1]
+institution = "KU Leuven"
+username = "alice"
+password = "token"
 ```
 
 Override `<zotcli-home>` with the `ZOTCLI_HOME` environment variable.
@@ -531,6 +557,7 @@ Override `<zotcli-home>` with the `ZOTCLI_HOME` environment variable.
 
 - Database opened with `sqlite3://…?mode=ro` — the OS-level read-only URI flag makes direct writes impossible
 - WAL journal detection warns if Zotero is currently open (pending writes may not be visible yet)
+- Network retrieval is optional and only used by `zot items fulltext` unless `--offline` is passed
 - Write operations route through Zotero's own connector HTTP server — never via direct SQLite mutation
 - Default is read-only; writes require explicit opt-in (`zot config set write.enabled true`)
 - No Zotero API key required

{zotcli-0.2.1 → zotcli-0.2.2}/SKILL.md

@@ -241,17 +241,30 @@ zot items list [--type TYPE] [--collection NAME] [--limit N]
 zot items show <id|key>
 zot items attachments <id|key>
 zot items notes <id|key>
-zot search "query" [--field title] [--author NAME] [--doi DOI] [--tag TAG] [--year YEAR]
+zot items fulltext <id|key> [--offline] [--playwright-auth/--no-playwright-auth]
+
+# Search
+zot search "query" [--field title] [--field abstract] [--type TYPE]
+zot search --author "Name"
+zot search --doi 10.xxxx/yyyy
+zot search --tag "tag-name"
+zot search --year 2020-2024
+zot search "query" --fulltext
+
+# Attachments
 zot attachments list [--missing] [--type pdf]
 zot attachments path <id|key>
 zot attachments open <id|key>
 zot export json|csv|bib|markdown --collection "Name" [--output file]
 zot export json|csv|bib|markdown --all [--output file]
+zot export markdown --all --notes --output report.md
 
 # Config (read-only-safe)
 zot config path
 zot config get <key>
 zot config set <key> <value>
+zot config library-auth --library 1 --institution "KU Leuven" --username "alice" --password "token"
+zot config library-auth --library 1 --show
 
 # Write — requires write.enabled=true and Zotero running
 zot add status
@@ -299,7 +312,24 @@ If it shows unreachable, trigger the protocol above **before** attempting the ad
 
 - Database opened in **strict read-only URI mode** (`sqlite3://…?mode=ro`) — impossible to corrupt your Zotero library via direct SQL
 - WAL journal detection: warns if Zotero is currently running (changes may not be visible yet)
+- Network calls are optional and used only by `zot items fulltext` unless `--offline` is passed
 - Writes only via Zotero's own connector HTTP server — never via direct SQLite mutation for item data. Default is read-only; writes require explicit opt-in (`zot config set write.enabled true`)
 - **One exception:** `zot collection assign` (and `zot add … --collection` on a duplicate) writes a single row into `collectionItems`, the join table that records which items belong to which collections. This table carries no sync-critical metadata (no version counters, no timestamps) so the write is safe even while Zotero is open. Zotero will pick up the change on its next UI refresh.
 - No Zotero API key required
 - All credentials stored at rest in `<zotcli-home>/credentials.json` (mode 0600 on POSIX)
+
+### Full-text retrieval strategy
+
+`zot items fulltext` uses this order:
+1. direct network access (institution/network location),
+2. config credentials (`zot config library-auth`),
+3. Playwright interactive authentication fallback,
+4. local Zotero fulltext index,
+5. metadata fallback (title/abstract/notes).
+
+## Running tests
+
+```bash
+python3 -m pytest tests/ -q          # unit + integration tests (in-memory DB fixture)
+python3 -m pytest tests/e2e -m e2e   # End-to-end against real zotero.sqlite (slow)
+```

{zotcli-0.2.1 → zotcli-0.2.2}/docs/commands.md

@@ -88,6 +88,8 @@ zot items show AABB0001
 
 zot items attachments <id|key>             # Attachments with path + existence check
 zot items notes <id|key>                   # Attached notes (HTML stripped)
+zot items fulltext <id|key>                # Network-first full-text retrieval
+zot items fulltext <id|key> --offline      # Only local Zotero fulltext/metadata
 ```
 
 `<id|key>` accepts a numeric item ID or the 8-character Zotero key (e.g. `AABB0001`).
@@ -192,6 +194,29 @@ zot export bib --collection "NLP"
 
 ---
 
+## `zot config`
+
+Manage local CLI configuration values.
+
+```bash
+zot config library-auth --library 1 --institution "KU Leuven" --username "alice" --password "token"
+zot config library-auth --library 1 --show
+```
+
+`library-auth` stores optional per-library institutional/login details used when direct network-location access to full text fails.
+
+### Full-text retrieval strategy (`zot items fulltext`)
+
+The command follows this order:
+
+1. **Direct network access** from DOI/URL (works immediately on institutional networks like campus/VPN).
+2. **Config credentials** from `zot config library-auth` (username/password flow).
+3. **Playwright-assisted login** (interactive browser fallback).
+4. **Local Zotero fulltext index**.
+5. **Metadata fallback** (title/abstract/notes).
+
+---
+
 ## Item types reference
 
 Common values for `--type`:

{zotcli-0.2.1 → zotcli-0.2.2}/docs/getting_started.md

@@ -27,6 +27,10 @@ zot search "bayesian" --field title
 
 # Get attachment paths for a specific item
 zot attachments path <ITEM_ID_OR_KEY>
+
+# Retrieve full text (network-first, then auth/local fallbacks)
+zot items fulltext <ITEM_ID_OR_KEY>
+zot items fulltext <ITEM_ID_OR_KEY> --offline
 ```
 
 ## Programmatic Usage (SDK)
@@ -62,3 +66,7 @@ def extract_pdfs():
 print("Extracting PDFs...")
 extract_pdfs()
 ```
+
+### CLI preview (fulltext + auth config)
+
+![Fulltext and auth CLI preview](images/fulltext-auth-flow.png)

{zotcli-0.2.1 → zotcli-0.2.2}/docs/index.md

@@ -8,6 +8,7 @@
 - **Read-Only**: Safe to use. Never writes to the database.
 - **Python SDK**: Rich programmatic access to your Zotero library via Pydantic models.
 - **CLI Tool**: Powerful `zot` command-line interface for browsing, searching, and exporting.
+- **Full-text Retrieval Flow**: Network-first retrieval with config-auth and Playwright fallback.
 
 ## Project Layout
 

{zotcli-0.2.1 → zotcli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zotcli"
-version = "0.2.1"
+version = "0.2.2"
 description = "A CLI for browsing, exporting, and adding items to a Zotero library"
 readme = "README.md"
 requires-python = ">=3.10"

{zotcli-0.2.1 → zotcli-0.2.2}/src/zotcli/__init__.py

@@ -1,3 +1,3 @@
 """zotcli — A read-only CLI for browsing and exporting a Zotero library."""
 
-__version__ = "0.1.3"
+__version__ = "0.2.2"

zotcli-0.2.2/src/zotcli/cli/config_cmd.py

@@ -0,0 +1,101 @@
+"""CLI group: zot config — read/write zotcli configuration and per-library auth."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from zotcli.cli.main import Context, pass_ctx
+from zotcli.cli.render import make_console
+from zotcli.config import get_library_auth, set_library_auth
+
+
+@click.group("config")
+def config_cmd():
+    """Manage zotcli settings."""
+
+
+@config_cmd.command("path")
+def config_path_cmd():
+    """Print the zotcli home directory path."""
+    from zotcli.paths import zotcli_home
+    click.echo(str(zotcli_home()))
+
+
+@config_cmd.command("get")
+@click.argument("key")
+def config_get(key: str):
+    """Print the value of KEY (section.key form, e.g. write.enabled).
+
+    Exits with code 1 if the key is not set.
+    """
+    from zotcli.config import get_config_value
+    val = get_config_value(key)
+    if val is None:
+        click.echo(f"Key '{key}' is not set.", err=True)
+        sys.exit(1)
+    click.echo(val)
+
+
+@config_cmd.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str):
+    """Set KEY to VALUE and persist to <zotcli-home>/config.toml.
+
+    Supported keys include: write.enabled, write.connector_url,
+    unpaywall.email, and any other dotted section.key value.
+    """
+    from zotcli.config import set_config_value
+    set_config_value(key, value)
+    click.echo(f"Set {key} = {value}")
+
+
+@config_cmd.command("library-auth")
+@click.option("--library", "library_id", type=int, default=None, help="Library ID (default: current)")
+@click.option("--institution", default=None, help="Institution/library provider name")
+@click.option("--username", default=None, help="Library login username")
+@click.option("--password", default=None, help="Library login password/token")
+@click.option("--show", is_flag=True, help="Show current authentication details")
+@pass_ctx
+def library_auth(
+    ctx: Context,
+    library_id: int | None,
+    institution: str | None,
+    username: str | None,
+    password: str | None,
+    show: bool,
+):
+    """Store or display per-library authentication details for full-text retrieval."""
+    console = make_console(ctx.color)
+    lib_id = library_id if library_id is not None else ctx.library_id
+
+    if show:
+        auth = get_library_auth(lib_id)
+        if not any(auth.values()):
+            console.print(f"[dim]No auth details configured for library {lib_id}.[/dim]")
+            return
+        masked_password = "******" if auth["password"] else ""
+        console.print(f"Library: {lib_id}")
+        console.print(f"Institution: {auth['institution']}")
+        console.print(f"Username: {auth['username']}")
+        console.print(f"Password: {masked_password}")
+        return
+
+    institution_value = institution or click.prompt("Institution", default="", show_default=False)
+    username_value = username or click.prompt("Username", default="", show_default=False)
+    password_value = password or click.prompt(
+        "Password / token",
+        default="",
+        show_default=False,
+        hide_input=True,
+    )
+
+    set_library_auth(
+        lib_id,
+        institution=institution_value.strip(),
+        username=username_value.strip(),
+        password=password_value,
+    )
+    console.print(f"[green]Saved auth details for library {lib_id}.[/green]")

{zotcli-0.2.1 → zotcli-0.2.2}/src/zotcli/cli/items.py

@@ -6,10 +6,12 @@ import click
 from rich.panel import Panel
 from rich.table import Table
 
-from zotcli.cli.main import pass_ctx, Context
-from zotcli.cli.render import make_console, item_panel, items_table
-from zotcli.queries.items import get_items, get_item
+from zotcli.cli.main import Context, pass_ctx
+from zotcli.cli.render import item_panel, items_table, make_console
+from zotcli.config import get_library_auth
 from zotcli.queries.collections import get_collection_by_name, get_items_in_collection
+from zotcli.queries.items import get_item, get_items
+from zotcli.queries.search import get_item_fulltext_with_strategy
 
 
 @click.group()
@@ -60,7 +62,7 @@ def show_item(ctx: Context, id_or_key: str):
     item = get_item(ctx.db, item_id)
     if item is None:
         raise click.ClickException(f"Item not found: {id_or_key!r}")
-    
+
     from zotcli.queries.collections import get_collection_by_id
     cols = []
     if item.collections:
@@ -118,3 +120,71 @@ def item_notes(ctx: Context, id_or_key: str):
 
     for note in item.notes:
         console.print(Panel(note.plain_text[:2000], title=note.title or "Note"))
+
+
+@items.command("fulltext")
+@click.argument("id_or_key")
+@click.option("--max-chars", default=10000, show_default=True, help="Maximum number of characters to print")
+@click.option("--offline", is_flag=True, help="Skip network/auth retrieval and only use local Zotero data")
+@click.option(
+    "--playwright-auth/--no-playwright-auth",
+    default=True,
+    show_default=True,
+    help="Use Playwright login fallback when direct/config retrieval fails",
+)
+@pass_ctx
+def item_fulltext(
+    ctx: Context,
+    id_or_key: str,
+    max_chars: int,
+    offline: bool,
+    playwright_auth: bool,
+):
+    """Retrieve full text for an item with network/auth/local fallback."""
+    console = make_console(ctx.color)
+    item_id_val = int(id_or_key) if id_or_key.isdigit() else id_or_key
+    auth = get_library_auth(ctx.library_id)
+
+    def _playwright_fetch(url: str) -> str | None:
+        if not playwright_auth:
+            return None
+
+        try:
+            from playwright.sync_api import Error as PlaywrightError
+            from playwright.sync_api import sync_playwright
+        except ImportError:
+            console.print(
+                "[yellow]Playwright fallback unavailable (install `playwright` + browser binaries).[/yellow]"
+            )
+            return None
+
+        console.print(
+            "[yellow]Open browser for manual institutional login.[/yellow]\n"
+            "Complete authentication in the opened window, then press Enter here."
+        )
+
+        try:
+            with sync_playwright() as p:
+                browser = p.chromium.launch(headless=False)
+                page = browser.new_page()
+                page.goto(url, wait_until="domcontentloaded", timeout=45000)
+                click.pause()
+                text = page.locator("body").inner_text(timeout=5000).strip()
+                browser.close()
+                return text or None
+        except (PlaywrightError, TimeoutError):
+            return None
+
+    text, source = get_item_fulltext_with_strategy(
+        ctx.db,
+        item_id_val,
+        prefer_network=not offline,
+        auth=auth,
+        playwright_fetcher=_playwright_fetch if playwright_auth and not offline else None,
+    )
+    if text is None:
+        raise click.ClickException(f"Item not found: {id_or_key!r}")
+
+    title = f"Full text for {id_or_key}"
+    console.print(f"[dim]Source: {source}[/dim]")
+    console.print(Panel(text[:max_chars], title=title))

{zotcli-0.2.1 → zotcli-0.2.2}/src/zotcli/cli/main.py

@@ -126,6 +126,7 @@ from zotcli.cli import attachments as _att_mod  # noqa: E402
 from zotcli.cli import search as _search_mod  # noqa: E402
 from zotcli.cli import stats as _stats_mod  # noqa: E402
 from zotcli.cli import export as _export_mod  # noqa: E402
+from zotcli.cli import config_cmd as _config_mod  # noqa: E402
 
 cli.add_command(_col_mod.collections)
 cli.add_command(_items_mod.items)
@@ -133,10 +134,9 @@ cli.add_command(_att_mod.attachments)
 cli.add_command(_search_mod.search)
 cli.add_command(_stats_mod.stats)
 cli.add_command(_export_mod.export)
+cli.add_command(_config_mod.config_cmd)
 
 # Import and register write-capability groups (M1+)
-from zotcli.cli.config_cmd import config as _config_cmd  # noqa: E402
 from zotcli.cli.add import add as _add_cmd  # noqa: E402
 
-cli.add_command(_config_cmd)
 cli.add_command(_add_cmd)

{zotcli-0.2.1 → zotcli-0.2.2}/src/zotcli/config.py

@@ -2,8 +2,7 @@
 
 from __future__ import annotations
 
-import os
-import sys
+import json
 from pathlib import Path
 
 try:
@@ -34,6 +33,7 @@ _DEFAULTS: dict = {
         "color": True,
         "page_size": 50,
     },
+    "library_auth": {},
 }
 
 # Defaults for the [write] section (stored in zotcli-home/config.toml)
@@ -68,11 +68,56 @@ def load_config() -> dict:
 
 def save_config(cfg: dict) -> None:
     """Persist config to disk (TOML format)."""
-    import tomli_w  # type: ignore[import]
     p = _config_path()
     p.parent.mkdir(parents=True, exist_ok=True)
-    with open(p, "wb") as f:
-        tomli_w.dump(cfg, f)
+    try:
+        import tomli_w  # type: ignore[import]
+
+        with open(p, "wb") as f:
+            tomli_w.dump(_strip_none(cfg), f)
+        return
+    except ImportError:
+        pass
+
+    lines: list[str] = []
+    for section, values in cfg.items():
+        if not isinstance(values, dict):
+            continue
+        lines.append(f"[{section}]")
+        for key, value in values.items():
+            if isinstance(value, dict):
+                lines.append(f"[{section}.{key}]")
+                for nested_key, nested_value in value.items():
+                    if isinstance(nested_value, dict):
+                        raise ValueError(
+                            "Fallback TOML writer supports only one level of nested tables; "
+                            "install tomli_w for deeper nesting."
+                        )
+                    if nested_value is None:
+                        continue
+                    lines.append(f"{nested_key} = {_toml_literal(nested_value)}")
+            else:
+                if value is None:
+                    continue
+                lines.append(f"{key} = {_toml_literal(value)}")
+        lines.append("")
+    p.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+
+
+def _strip_none(obj):
+    if isinstance(obj, dict):
+        return {k: _strip_none(v) for k, v in obj.items() if v is not None}
+    return obj
+
+
+def _toml_literal(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return str(value)
+    return json.dumps(str(value))
 
 
 def get_db_path(override: str | None = None) -> Path | None:
@@ -93,6 +138,38 @@ def get_library_id(override: int | None = None) -> int:
     return cfg.get("database", {}).get("library_id", 1)
 
 
+def get_library_auth(library_id: int) -> dict[str, str]:
+    cfg = load_config()
+    auth = cfg.get("library_auth", {}).get(str(library_id), {})
+    if not isinstance(auth, dict):
+        return {}
+    return {
+        "institution": str(auth.get("institution", "") or ""),
+        "username": str(auth.get("username", "") or ""),
+        "password": str(auth.get("password", "") or ""),
+    }
+
+
+def set_library_auth(
+    library_id: int,
+    *,
+    institution: str,
+    username: str,
+    password: str,
+) -> None:
+    cfg = load_config()
+    auth_section = cfg.setdefault("library_auth", {})
+    if not isinstance(auth_section, dict):
+        auth_section = {}
+        cfg["library_auth"] = auth_section
+    auth_section[str(library_id)] = {
+        "institution": institution,
+        "username": username,
+        "password": password,
+    }
+    save_config(cfg)
+
+
 # ---------------------------------------------------------------------------
 # Write-section helpers — config stored in <zotcli-home>/config.toml
 # ---------------------------------------------------------------------------