v3.1.0

The first minor release after 3.0: output you can pipe, deletes you can undo, and consistent flags. Nothing is removed or changed incompatibly in 3.x: every command and flag that works today still works. Where a spelling or behaviour is going away it prints a deprecation warning now and is removed in 4.0, and each item is listed in #462. Worth knowing:

• search, collection list, tag list, report stats, slr list * and system jobs list take --format json|csv, and item trash, item restore and a new --trash flag on item delete, item merge, slr dedupe, collection delete --recursive and item transfer --delete-source move things to Zotero's trash (recoverable) through the Web API, not only --offline.
• item delete, storage checkout and system restore still apply without a flag, but warn; from 4.0 they preview unless you pass --execute.
• The old flag spellings (--item-id, --item, --name on existing collections, --verbose on subcommands, --format on exports) keep working, with a warning, until 4.0.
• rag is deprecated and leaves zotero-cli in 4.0; it is becoming a separate tool.

Added

• --trash on the bulk deletes (Issue #402): collection delete --recursive, item merge (and --from-plan), slr dedupe and item transfer --delete-source take --trash to move what they would delete to Zotero's trash instead, where item restore (or Desktop) brings it back - so a merge or a transfer can be undone. Without it nothing changes: they still delete permanently. For collection delete --recursive --trash the items are recoverable but the collections themselves are still deleted for good (only items' trash was verified against the Web API), so restored items come back without them; the preview says so. slr prune needs no flag: it only removes items from a collection. Trash by default, with --permanent, is 4.0 (#462).
• item trash and item restore work online, and item delete --trash (Issue #402): moving an item to Zotero's trash no longer needs --offline. Online the commands set the item's deleted flag through the Web API - the property Zotero Desktop syncs - so the item appears in Desktop's trash, keeps its collections, and can be restored from either side; with --offline they still write Desktop's own rows to zotero.sqlite. Verified against a real library before building it (trash and restore, each 204, reflected in items/trash). Writes use the item's own version, so an item changed since it was read is refused, not overwritten. item delete --trash does the same in one step and applies without the item delete deprecation warning, being recoverable; --permanent and trash-by-default arrive in 4.0 (#462), and the bulk deletes take --trash too (below).
• --format {table,json,csv} on the commands you'd pipe next (Issue #380): search, collection list (tree stays the default; json/csv are flat key, name, parent, num_items records), tag list, report stats (json is one object, csv is long-form section, label, count, percent), slr list pending|included|excluded|qa-approved and system jobs list now print machine-readable output, not just item list. Stdout carries only the data - progress and notices go to stderr, and an empty result is an empty JSON list or a header-only CSV. The default output of every command is unchanged. The rendering moved into a shared presenters/records.py, which item list now uses too.
• OpenAlex API key, and one 429 policy for every metadata client (Issue #420): set openalex_api_key (or OPENALEX_API_KEY) to send your free OpenAlex key as api_key= on every request; it's masked in logs and listed, commented, in config.toml.example. OpenAlex's pricing page now describes a daily usage allowance per key, so unkeyed heavy use may run out. Every client built on BaseAPIClient now handles 429 the same way: wait the provider's Retry-After (at most 30 s) and retry twice, or fail at once with a warning naming the provider when it wants a longer wait (a daily quota) instead of a bare HTTP error. docs/DATA_SOURCES.md documents both.
• Item keys can be positional or --key everywhere they were one or the other (Issue #379): item inspect ABCD1234 now works (the docs already showed it), and slr sdb inspect|edit accept --key KEY as well as the positional.

Changed

• A stray argument now reports the subcommand's usage line (Issue #379): item inspect K --bogus prints usage: zotero-cli item inspect ... instead of the top-level usage.

Deprecated

• rag is deprecated and leaves zotero-cli in 4.0 (Issue #414): RAG is being rebuilt as a separate product that connects to your Zotero library on its own, so the rag commands (ingest, query, context, purge, model) and the [rag] extra will be removed in 4.0 (tracked in #462). Until then they keep working and every rag command prints a deprecation warning to stderr. The release binaries never included them.
• --as {bibtex,ris,md} names the export type; --format on exports is deprecated (Issue #380): item export, item inspect and collection export now take --as, so --format always means how output is rendered. --format keeps working on those three as a hidden alias that prints a deprecation warning; it is removed in 4.0 (Issue #462). slr snowball export --format and rag query --format are unchanged.
• --key and --collection are the standard spellings (Issue #379): item move --item-id, tag add --item, and the --name flag of collection backup, collection export, collection purge, slr sdb reset and slr source add (where it names an existing collection) are now --key / --collection. The old spellings keep working as hidden aliases that print a deprecation warning; they are removed in 4.0 (Issue #462). Flags that create a name (collection create/rename --name, slr source init --name, system demo-sandbox --name) are unchanged, as are the plural list flags (--keys, --collections) and --master/--tree, which mean something different.
• The 11 per-command --verbose flags are renamed --details (Issue #374): import file/arxiv/doi/bdtd, item pdf fetch/strip, collection clean, report audit, slr report prisma, slr source add and slr reconcile now take --details, which never touches the global -v (debug logging). --verbose on those commands keeps working as a hidden alias for one minor release, printing a deprecation warning; it is removed in 4.0 (Issue #462).
• item delete, storage checkout and system restore gain --dry-run/--execute (Issue #378): all three predate the preview-by-default policy and still apply immediately when neither flag is given - that keeps working unchanged in 3.x, but now prints a deprecation warning to stderr telling you to pass --execute. item delete --dry-run also now previews the item and lists its attached notes/files (which the Web API's DELETE doesn't cascade to - they'd become orphaned, not deleted). storage checkout --dry-run lists what would be downloaded and relinked without touching the filesystem or the library. All three switch to preview-by-default in 4.0 (Issue #462).

---

Verifying downloads: SHA256SUMS lists the checksum of every file
(sha256sum -c SHA256SUMS --ignore-missing). Each file also has signed build
provenance: gh attestation verify <file> -R fchicout/zotero-cli confirms it
was built by this repository's release workflow.

PyPI: uv tool install zotero-command-line==3.1.0 (or pipx install).