Command reference¶

Every zotio command, generated directly from the binary. Add --agent to any command for JSON output and non-interactive defaults; mutating commands preview unless --yes is passed.

Read commands emit a {meta, results} envelope in JSON mode; for ordinary list/single-resource reads, results is always a JSON array, even for a single-object read like items get (a one-element array) — index it as results[0] or iterate with results[] uniformly. analytics is in this group too: every mode answers results rows carrying a count, so one jq works across --group-by, --type, and the no-flag resource breakdown. Purpose-built report-shaped diagnostics are explicit exceptions: items audit, journal show, doctor, which, schema drift, capabilities drift, workflow status, reading-list, items duplicates, items citekey-conflicts, items bibcheck, library health, library prisma, and creators audit expose named report fields instead of results. annotations export is also an explicit raw-export exception: its --format markdown and --format json outputs are consumable documents, not read-list envelopes.

A read command may also emit sibling top-level keys beside its own payload, for advisory data it did NOT match. Three commands do this, and they share one naming convention so the grammar is learned once: the rows arrive under near_<selector>_<thing>, the outcome under meta.<selector>_lookup, and the truncation count under meta.near_<selector>_total. items find --title reports near_title_matches (rows {key, title, score, year, item_type, trashed}) with meta.title_lookup; items find --citekey reports near_citekey_matches (rows {cite_key, item_key, title, score}) with meta.citekey_lookup; items duplicates --by title|all reports near_title_groups (rows {group, score, count, keys, titles, item_type, requires_review}, where group is title_near) with meta.title_lookup. Rows are strongest first and the score is rounded to two decimals.

What a perfect score means differs by command, so do not apply one rule to all three. On items find --title 1.00 is unreachable: an equal title is an exact hit, so a near row is always capped below it. On items find --citekey 1.00 is reachable and is the strongest suggestion there is — the library holds that key differing only in case or Unicode encoding. On items duplicates 1.00 is reachable and expected: a fold-equal pair is two stored titles that differ only in case, punctuation or Unicode form, which is exactly the duplicate the equality detector cannot see.

The lookup-state key also differs, and this is the one an agent gets wrong. On items find it describes a lookup a person asked for: exact_hit (a returned row matched on that selector, and .results holds it), near_matches, no_near_matches, or near_lookup_failed; it is ABSENT when the question stayed unanswered, because the selector was not given or another selector matched while this one did not — the selectors are OR-ed and one identifier hit suppresses the report. On items duplicates nothing is looked up, so meta.title_lookup describes ONLY the advisory near pass and can never be exact_hit. The exact answer is the report body in .groups, which is always complete: a run reporting no_near_matches can still hold exact duplicate groups, so read .groups and do not treat that state as a clean library. --by doi reports not_requested, because that detector never asks the title question at all.

items duplicates adds meta.near_title_scan, which says whether the comparison was complete: complete, or common_words_skipped when some title words were carried by too many titles to pair on, so two titles whose only shared words were those were never compared. Read no_near_matches with common_words_skipped as "not everything was compared", never as "nothing is close". The key is absent after near_lookup_failed and for --by doi. A meta.near_<selector>_total key reports how many candidates were scored when more were scored than listed — for citekeys, how many distinct keys, since one key held by three items is one suggestion — and is absent when the list is complete, so "not in these rows" is never mistaken for "not in the library".

A sibling key is never folded into the payload, so .results and .groups keep holding only what the command matched and every existing pipeline is unaffected; these rows are suggestions to confirm, never matches, and items duplicates resolve will not merge a near group. --select and --compact apply to the payload only and never drop a sibling key or meta. Machine formats with no column for a score (--plain, --csv) print a one-line stderr note naming the count and --json; on items duplicates a second note names the words too common to pair on, and unlike the rows note it prints even when no rows were found. --quiet is exempt on a terminal, where the exit code is the whole answer; piped, items find still emits its envelope including the near rows. Under --group all sibling keys are kept per library at libraries[].extra and never merged, because a similarity score only ranks candidates inside the library that produced it — and items duplicates --group all REQUIRES --json (or --agent), exiting 2 otherwise, because its near rows exist only in the JSON report and no other format could carry them into the aggregate.

Global flags¶

These flags are available on every command.

Configuration¶

zotio loads its configuration from the platform configuration directory, or from the path supplied with --config. zotio doctor reports the active path.

Update checks¶

Release discovery is off by default. To opt in to one anonymous GitHub releases request per day, add:

[updates]
check = true

The request reads only the public zotio releases feed; it sends no identifying payload, never installs anything, and failures are ignored. zotio doctor reports whether a newer version is available.

zotio agent-context¶

Emit structured JSON describing this CLI for agents

Outputs a machine-readable description of commands, flags, and auth so agents can introspect this CLI at runtime without parsing --help or reading source. Schema is versioned via schema_version.

zotio agent-context [flags]

zotio analytics¶

Analyze a synced Zotero library

Analyze locally synced Zotero data.

--type accepts a mirrored resource kind (such as items or collections) for resource counts. --item-type accepts a Zotero item type (such as journalArticle or book) to count only matching rows in the items mirror. When --group-by is supplied, the item rows are grouped by year, itemType, collection, creator, or tag. --limit caps the groups shown (0 = no limit).

zotio analytics [flags]

Examples:

# Count all items and only journal articles
  zotio analytics --type items
  zotio analytics --item-type journalArticle --json

  # Group items by publication year or collection
  zotio analytics --type items --group-by year
  zotio analytics --type items --group-by collection --limit 10 --json

zotio annotations¶

Search and export annotations from your Zotero library

zotio annotations

zotio annotations export¶

Export annotations as markdown or JSON

Export annotations grouped by the top-level item that owns them. --limit caps the number of annotations exported, not the number of items scanned. --collection and --tag are shorthand for --scope collection:KEY and --scope tag:NAME; together they intersect.

With --data-source auto (the default) the command reads live and serves the local mirror when Zotero is unreachable. --format json returns the {meta, results} envelope; under --json or --agent, --format markdown returns {"format", "content"}. With --output the result goes to the file and stdout reports what was written; under --dry-run nothing is written.

zotio annotations export [flags]

Examples:

zotio annotations export --collection ABCD2345 --output notes.md
  zotio annotations export --scope "collection:ABCD2345 AND tag:to-read" --format json
  zotio annotations export --limit 200 --output annotations.md --dry-run

zotio annotations search¶

Search annotations by text

Search annotation text, comments and tags.

By default the search uses the local store's full-text index: word stems match ("trust" finds "trusted"), "quoted phrases" match exactly, AND, OR, NOT and parentheses combine terms, and results are ranked by relevance. Live search has none of that, which is why this command reads the local store first, unlike annotations timeline and annotations export, which read live first. With no synced local store the search runs live instead: each word or "quoted phrase" must appear, in any letter case, in the annotation's text, comment or tags; stems and operators do not apply. meta.source and meta.reason say which path answered.

--data-source local searches the index only. --data-source live (or --refresh) searches live only.

Results include the key and title of the top-level item each annotation belongs to. --scope names top-level items, as it does for annotations export and annotations timeline.

zotio annotations search <query> [flags]

Examples:

zotio annotations search "working memory"
  zotio annotations search trust --scope collection:ABCD2345 --color yellow
  zotio annotations search "effect size" --data-source local --limit 20

zotio annotations timeline¶

List annotations sorted by creation date

List annotations newest first. --item names the top-level item that owns the annotations, never the attachment that holds them. --collection and --item are shorthand for --scope collection:KEY and --scope item:KEY.

With --data-source auto (the default) the command reads live and serves the local mirror when Zotero is unreachable.

zotio annotations timeline [flags]

Examples:

zotio annotations timeline --limit 50
  zotio annotations timeline --since 2024-01-01
  zotio annotations timeline --item ABCD2345 --json
  zotio annotations timeline --scope "collection:ABCD2345 AND tag:to-read"

zotio attachments¶

Attachment file operations

zotio attachments

zotio attachments add¶

Attach a local file to an existing item

Attach a local file (typically a PDF) to an existing item. Mode "stored" uploads an imported_file child that syncs to all devices. Mode "linked-file" records the absolute local path without consuming Zotero storage quota; the bytes remain local to this machine.

A stored upload through the Zotero Web API always lands in Zotero's OWN cloud storage and is billed against that storage plan. When Zotero desktop keeps files elsewhere (a personal WebDAV server, or file syncing turned off) that upload is refused rather than silently misrouted.

--via connector is the local route for that case. Zotero's connector cannot attach to an item that already exists, so this creates a temporary parent and the file in one connector session — putting the bytes in whatever file store the desktop actually uses — then moves the attachment onto your item and trashes the temporary parent. Moving it relocates no bytes: every storage name derives from the attachment's own key, not its parent's. Requires Zotero desktop running.

The route is opt-in and never chosen by --via auto, because it creates and trashes a temporary item in your library. Pass --allow-zotero-cloud instead to accept the cloud upload.

All routes are retry-safe. Stored files reconcile by filename and registered MD5, and linked files by absolute path. The connector route reconciles on content hash alone, because Zotero names the stored file after the parent item rather than after your file: an identical retry no-ops, a run interrupted before the move is resumed rather than duplicated, and an empty temporary parent left by a run interrupted after the move is trashed by an identical retry once it is more than seven minutes old. Two limits are worth knowing: a retry issued before Zotero has registered the hash can still add a second copy, and two simultaneous runs against one item can both add one.

By default this previews the planned attachment; apply with --yes.

zotio attachments add <parent-key> <file> [flags]

zotio auth¶

Manage authentication for Zotero

zotio auth

zotio auth logout¶

Clear stored credentials

Previews by default: shows what would be cleared and changes nothing. Pass --yes to clear the stored API key from the config file and remove the credentials file.

zotio auth logout

Examples:

zotio auth logout
  zotio auth logout --yes

zotio auth set-token¶

Save an API token to the config file

zotio auth set-token --stdin [flags]

Examples:

printf %s "$ZOTERO_API_KEY" | zotio auth set-token --stdin

zotio auth status¶

Show authentication status

zotio auth status

Examples:

zotio auth status

zotio capabilities¶

Emit the machine-readable capability + preconditions registry

Outputs a typed registry describing each command's operation kind (read/write/destructive), write target, supported data sources, and preconditions (live_local_api, web_api_key, synced_store, better_bibtex, desktop_connector, zotero_file_storage) so agents can select safe commands and pre-flight requirements without parsing --help or guessing from names. Commands with more than one write route carry a routes list where each route names its own preconditions; the top-level requires and write_target describe the default route (the first entry in routes).

A destructive command makes a change "journal undo" cannot reverse. A command that writes local files you name (an export, a report, a baseline) keeps operation read and reports write_target local_file.

zotio capabilities [flags]

zotio capabilities drift¶

Probe core read endpoints for capability/API drift

Probes core Zotero read endpoints declared in the capability registry and reports any endpoint that now returns an API error or cannot be reached. This is read-only and treats every non-nil GET error as drift, including HTTP 4xx/5xx and network failures.

zotio capabilities drift

zotio collections¶

Manage collections in your Zotero library

Manage collections in your Zotero library.

This group covers the collections themselves (create, update, move, delete, list, export); it does not add items to a collection. To add an item, use 'zotio items move --to ' (by key, also --from and --keys-from for many items at once) or 'zotio items add-to-collection --collection-name ' (by name, creating the collection if it does not exist yet).

zotio collections

zotio collections bundle¶

Write a local research package for a collection

Assemble a self-contained research package from the local store for a collection: synthesis context, annotations, and compact bibliography. This command never writes to Zotero; run sync first if local data is missing.

Re-running into the same --output-dir replaces the package; the result names every existing file it replaced. zotio-bundle.json is written last and lists each file's size and SHA-256: the package is complete only while that file is present and matches. With --dry-run nothing is written; the result lists the files that would be written and replaced.

zotio collections bundle <collectionKey> [flags]

Examples:

zotio collections bundle ABCD2345 --output-dir ./research/ethics
  zotio collections bundle ABCD2345 --output-dir ./research/ethics --dry-run

zotio collections create¶

Create one or more collections

zotio collections create [flags]

Examples:

zotio collections create --name "Reading list" --parent-collection ABCD2345

zotio collections delete¶

Delete a collection (does not delete items)

zotio collections delete <collectionKey>

Examples:

zotio collections delete ABCD2345

zotio collections export¶

Export a collection (and subcollections) as BibTeX, RIS, CSL-JSON, or item JSON

Recursively walks a collection and all its subcollections, then emits a single combined export in the requested format. Use --flat to export only the top-level collection without recursing into subcollections.

bibtex, ris, and csljson are rendered by Zotero's export translators, so they need Zotero desktop running. --format json emits the structured item JSON the synced mirror already holds, so it also works with Zotero closed (--data-source local, or auto once the local API stops answering).

The collection must exist: an unknown key exits 3 before anything is written. Under --json or --agent, bibtex and ris output is wrapped as {"format": ..., "content": ...}. With --output the file is replaced atomically and the result reports whether it replaced an existing file; with --dry-run nothing is written, not even a lock file, and the result reports what would be.

zotio collections export <collectionKey> [flags]

Examples:

# Export collection as BibTeX (default)
  zotio collections export ABCD2345

  # Export as RIS to a file
  zotio collections export ABCD2345 --format ris -o refs.ris

  # Preview the file write without creating it
  zotio collections export ABCD2345 -o refs.bib --dry-run

  # Export the whole subtree's item JSON from the synced mirror, Zotero closed
  zotio collections export ABCD2345 --format json --data-source local

  # Export without descending into subcollections
  zotio collections export ABCD2345 --flat

zotio collections gaps¶

Find highly cited DOI references missing from a collection's library

zotio collections gaps <collectionKey> [flags]

Examples:

zotio collections gaps ABCD2345 --limit 100 --top 10

zotio collections get¶

Get a specific collection

zotio collections get <collectionKey>

Examples:

zotio collections get ABCD2345

zotio collections items¶

List all items in a collection

zotio collections items <collectionKey> [flags]

Examples:

zotio collections items ABCD2345 --limit 25

zotio collections list¶

List all collections

zotio collections list [flags]

Examples:

zotio collections list --limit 50

zotio collections move¶

Move a collection under a new parent

zotio collections move <collectionKey> --to <parentKey> [flags]

Examples:

zotio collections move ABCD2345 --to EFGH6789
  zotio collections move ABCD2345 --to root

zotio collections stats¶

Show analytics for a collection (item count, PDF coverage, year range, top journals)

zotio collections stats <collectionKey> [flags]

Examples:

zotio collections stats ABCD2345 --top 10

zotio collections subcollections¶

List subcollections of a collection

zotio collections subcollections <collectionKey>

Examples:

zotio collections subcollections ABCD2345

zotio collections tags¶

List tags used within a collection

zotio collections tags <collectionKey> [flags]

Examples:

zotio collections tags ABCD2345 --query ethics

zotio collections top¶

List only top-level collections (no parents)

zotio collections top [flags]

Examples:

zotio collections top --limit 20

zotio collections update¶

Update a collection

zotio collections update <collectionKey> [flags]

Examples:

zotio collections update ABCD2345 --name "Reading list"

zotio creators¶

Audit creator names across your Zotero library

zotio creators

zotio creators audit¶

Audit synced creator names for variant candidates

Audit synced creator names for variant candidates without mutating Zotero.

The audit reads item creators from the local synced store and groups likely name variants into three confidence tiers: exact-after-normalization, initial/full-name compatibility, and ambiguous same-surname diagnostics. Ambiguous groups are hidden unless --include-ambiguous is supplied; when shown, they are review-only and never include runnable rename commands. Use --orcid to fetch CrossRef author ORCIDs for DOI-bearing tier-2/3 candidates and store them in the local creator_orcids sidecar table as corroboration evidence. That sidecar is local-only evidence; zotio never writes ORCIDs back to Zotero because Zotero has no creator ORCID field.

zotio creators audit [flags]

Examples:

zotio creators audit
  zotio creators audit --scope collection:ABCD1234
  zotio creators audit --orcid --json

zotio creators audit fix¶

Apply safe creator variant renames from creators audit

Apply safe creator variant renames from creators audit through the shared mutation preview/apply envelope.

By default this previews item writes without sending network mutations. Pass --yes to apply. Tier-1 exact-normalized groups are planned automatically. Tier-2 initial/full-name groups are planned only for explicit repeatable mappings such as --map "J. Smith=John Smith". Tier-3 ambiguous groups are never planned.

Creator renames PATCH each affected item with its full creators array and a version precondition, preserving creatorType, creator order, and unrelated creators. Applied creator renames are journaled for audit history, but journal undo does not reverse them because ordered creator-array inverses are not supported.

zotio creators audit fix [flags]

Examples:

# Previews also need --allow-destructive to show ok:true
  zotio creators audit fix --allow-destructive
  zotio creators audit fix --map "J. Smith=John Smith" --allow-destructive
  zotio creators audit fix --scope collection:ABCD2345 --allow-destructive --yes

zotio creators rename¶

Rename a creator display name across matching items

Rename a creator's display name across every item in scope that carries it.

This is the fix half of creators audit: run creators audit first to find variant groups, then apply the rename it suggests (or any alias/canonical pair of your own choosing) with this command.

The rename PATCHes each affected item with its full creators array and a version precondition, preserving creatorType, creator order, and unrelated creators. It handles both creator shapes: firstName/lastName and a single name field.

zotio creators rename --from <oldName> --to <newName> [flags]

Examples:

# Without --allow-destructive the preview is refused (ok:false, destructive_opt_in_required)
  zotio creators rename --from "Adam J Rock" --to "Adam J. Rock" --allow-destructive
  zotio creators rename --from "Adam J Rock" --to "Adam J. Rock" --allow-destructive --yes
  zotio creators rename --from "Adam J Rock" --to "Adam J. Rock" --scope collection:ABCD2345 --allow-destructive

zotio demo¶

Seed a zero-setup sample library and print a guided tour

Seed a bundled sample library into a separate demo store and print a short tour of commands to try.

The demo library is a separate SQLite database (demo.db) beside your real store. Set ZOTIO_DEMO=1 and pass --data-source local to keep reads inside it. Without that flag, the default auto source can query a running Zotero desktop. No Zotero desktop and no API key are required for local demo reads.

zotio demo [flags]

zotio desktop¶

Report whether Zotero desktop is running, or wait for it to start

zotio desktop

zotio desktop status¶

Report whether Zotero desktop is running and its connector accepts requests

Report whether Zotero desktop is running and whether its connector accepts requests. Cheap and local: it reads the profile lock of every discovered Zotero profile and sends one ping to the local connector. It exits 0 whatever it finds; read the fields, not the exit code.

Two signals, reported separately:

running Zotero's process is up: another process holds the profile lock (.parentlock via fcntl on macOS and Linux, parent.lock opened exclusively on Windows), or the connector answered. connector_reachable GET /ping answered 200 within 3s during this check. Imports and every other connector write need this.

state: ready the connector answers. starting the lock is held, the connector does not answer yet, and the lock is younger than the 2-minute startup window. Zotero takes the lock about 3s after launch and its connector listens a few seconds later. busy the lock is older than the startup window and the connector port accepted the connection but did not answer in this check (or answered with an error). One silent check is not a hang: a large sync can hold Zotero's main thread for seconds. unresponsive desktop wait only: the connector stayed silent for at least 60s across 3 or more checks (each allowed 10s): Zotero is open but not responding. connector_off the lock is older than the startup window and nothing listens on the connector port (every address refused repeated connects): the connector is disabled (Settings -> Advanced -> "Allow other applications to communicate with Zotero") or on another port. stopped neither signal holds.

The lock age comes from the lock file's modification time, which Zotero resets when it takes the lock (profiles[].lock_since). evidence names the strongest signal: connector, profile_lock, none.

Profiles are discovered from profiles.ini in the platform's Zotero directory (ZOTERO_PROFILE_DIR pins one); data_dir comes from the profile's prefs.js.

zotio desktop status

Examples:

zotio desktop status
  zotio desktop status --agent

zotio desktop wait¶

Block until Zotero desktop's connector accepts requests

Block until Zotero desktop's connector accepts requests, then print the status that proved it. If the connector already answers, it returns at once.

While Zotero is closed nothing runs on a timer: the command sleeps on filesystem notifications for the Zotero profile and data directories and probes only after a change. While Zotero is starting, the connector is re-checked on a capped backoff (250ms up to 2s), because it listens a few seconds after the lock and its start writes no file. When the startup window passes, a connector that cannot take a request is re-checked every 20s with a 10s ping. Any answer ends the wait as ready. 60s without one, across 3 or more checks, ends it with exit 15: unresponsive if any check found a listener on the connector port, connector_off if none did (a hung Zotero's listener also refuses some connects, so one refusal proves nothing). Exit 15 means Zotero is open but stuck: nothing on disk announces a recovery, so the caller tells the user and decides when to wait again. While Zotero is starting or busy, filesystem events cause no extra checks.

Two signals, reported separately:

running Zotero's process is up: another process holds the profile lock (.parentlock via fcntl on macOS and Linux, parent.lock opened exclusively on Windows), or the connector answered. connector_reachable GET /ping answered 200 within 3s during this check. Imports and every other connector write need this.

state: ready the connector answers. starting the lock is held, the connector does not answer yet, and the lock is younger than the 2-minute startup window. Zotero takes the lock about 3s after launch and its connector listens a few seconds later. busy the lock is older than the startup window and the connector port accepted the connection but did not answer in this check (or answered with an error). One silent check is not a hang: a large sync can hold Zotero's main thread for seconds. unresponsive desktop wait only: the connector stayed silent for at least 60s across 3 or more checks (each allowed 10s): Zotero is open but not responding. connector_off the lock is older than the startup window and nothing listens on the connector port (every address refused repeated connects): the connector is disabled (Settings -> Advanced -> "Allow other applications to communicate with Zotero") or on another port. stopped neither signal holds.

The lock age comes from the lock file's modification time, which Zotero resets when it takes the lock (profiles[].lock_since). evidence names the strongest signal: connector, profile_lock, none.

Exit codes and the JSON outcome field: 0 outcome "ready": the connector answers. 15 outcome "unresponsive" or "connector_off" (the state): Zotero runs past its startup window and its connector cannot take requests. 14 outcome "timeout": --timeout passed first; wait again. 9 outcome "no_profile" (no Zotero profile found and the connector does not answer) or "watch_failed" (the directories could not be watched). 10 the configured base URL is not a local Zotero, so there is no connector to wait for. 1 interrupted (SIGINT/SIGTERM) or stdin closed under --watch-stdin; nothing is printed on stdout.

--timeout replaces the global request timeout for this command; a connector ping is bounded to 3s, or 10s for the stall re-checks past the startup window.

zotio desktop wait [flags]

Examples:

zotio desktop wait
  zotio desktop wait --agent --timeout 6h
  # Supervised: exit when the supervisor's pipe closes
  zotio desktop wait --agent --watch-stdin --timeout 1h

zotio doctor¶

Check CLI health

Check CLI health.

When [updates].check is enabled, doctor also checks zotio's public GitHub releases feed at most once a day.

zotio doctor [flags]

Examples:

zotio doctor
  zotio doctor --json
  zotio doctor --fail-on stale

zotio export¶

Export data to JSONL or JSON for backup, migration, or analysis

Export paginated API data to a local file. Output defaults to JSONL (one JSON object per line, streaming-friendly); JSON output is available for backwards-compatible resource exports.

zotio export <resource> [id] [flags]

Examples:

# Export all items as JSONL (streaming, recommended for large datasets)
  zotio export items --output data.jsonl

  # Export with limit
  zotio export items --limit 1000

  # Pipe to another tool
  zotio export items | jq '.key'

zotio export snapshot¶

Reproducible, resumable paginated export with a content manifest

Export every page of a library, collection, or tag scope as JSONL, BibTeX, RIS, or CSL-JSON. A sidecar manifest (

.manifest.json) records each item's key, version, and canonical data hash for drift detection. An interrupted run continues with --resume using

.checkpoint.json. Translator formats need Zotero to return the requested include field.

Scope uses the shared --scope grammar: library (default), collection:KEY, tag:NAME, or collection:KEY AND tag:NAME. The data file and the manifest are each published atomically (a temporary file renamed into place), so a failed run keeps the previous snapshot. A JSONL run keeps its in-progress data in

zotio export snapshot [scope] [flags]

zotio export snapshot --output backup.jsonl
  zotio export snapshot --format bibtex --output library.bib
  zotio export snapshot collection:ABCD2345 --format ris --output coll.ris
  zotio export snapshot "collection:ABCD2345 AND tag:to-read" --output subset.jsonl
  zotio export snapshot --format csljson --output library.json --resume

zotio export snapshot verify <manifest.json> [flags]

zotio export snapshot verify backup.jsonl.manifest.json
  zotio export snapshot verify library.bib.manifest.json --fail-on-drift
  zotio export snapshot verify backup.jsonl.manifest.json --json

zotio feedback [text] [flags]

zotio feedback list [flags]

zotio feedback list
  zotio feedback list --limit 5
  zotio feedback list --json

zotio groups

zotio groups inspect <group-id>

zotio groups inspect 1234567 --json

zotio groups list

zotio groups list
  zotio groups list --json

  # Then sync and search a specific group:
  zotio sync --group <id>
  zotio search --group <id> <query>

zotio import <resource> [flags]

# Preview an import without sending anything (the default)
  zotio import <resource> --input data.jsonl

  # Apply the import
  zotio import <resource> --input data.jsonl --yes

  # Import from stdin
  cat data.jsonl | zotio import <resource> --input - --yes

zotio import apply <manifest> [flags]

zotio import arxiv <id> [flags]

zotio import discover [flags]

zotio import doi <doi> [flags]

zotio import file <path> [flags]

zotio import isbn <isbn> [flags]

zotio import monitor [flags]

zotio import monitor --author 0000-0002-1825-0097 --since 2026-01-01 --output new-works.json
  zotio import monitor --query "bayesian inference" --author A5023888391 --since 2026-09-01 --output feed.json
  zotio import resolve new-works.json > reviewed.json && zotio import apply reviewed.json

zotio import pdf <path...> [flags]

zotio import pmid <pmid> [flags]

zotio import resolve <dir-or-manifest> [flags]

zotio import scan <dir> [flags]

zotio import scan ~/Downloads/papers
  zotio import scan ~/Downloads/papers --resolve --json

zotio import targets

zotio import translators <url>

zotio import url <url> [flags]

zotio init [flags]

zotio items

zotio items add-to-collection <itemKey> [flags]

zotio items add-to-collection ABCD2345 --collection-name "Reading list"
  zotio items add-to-collection ABCD2345 --collection-name "Reading list" --yes

zotio items annotations <itemKey> [flags]

zotio items audit [flags]

zotio items authors [flags]

zotio items bibcheck <manuscript...> [flags]

zotio items bibcheck paper.tex
  zotio items bibcheck manuscript.md --fail-on-unknown
  zotio items bibcheck paper.tex chapter.md --json
  zotio items bibcheck chapter.qmd --fail-on high
  zotio items bibcheck paper.tex --check-retractions --fail-on high

zotio items bibliography [flags]

zotio items bibliography --scope collection:ABCD2345 --style apa
  zotio items bibliography --scope tag:to-submit --format csljson
  zotio items bibliography --scope collection:ABCD2345 --format bibtex
  zotio items bibliography --scope item:ABCD2345 --json
  zotio items bibliography --manuscript paper.tex --format biblatex
  zotio items bibliography --manuscript thesis.tex --follow-includes --format bibtex
  zotio items bibliography --manuscript intro.md --manuscript methods.md --format csljson

zotio items children <itemKey> [flags]

zotio items children ABCD2345

zotio items cite <itemKey> [flags]

zotio items cite ABCD2345
  zotio items cite ABCD2345 --style apa
  zotio items cite ABCD2345 --style bibtex --json

zotio items citekey-conflicts [flags]

zotio items citekey-conflicts
  zotio items citekey-conflicts --missing
  zotio items citekey-conflicts --conflicts --json

zotio items collections-of <itemKey>

zotio items create [flags]

zotio items create --items '[{"itemType":"journalArticle","title":"A title"}]'

zotio items delete <itemKey> [flags]

zotio items delete ABC12345

zotio items duplicates [flags]

zotio items duplicates resolve [flags]

zotio items duplicates resolve
  zotio items duplicates resolve --doi
  zotio items duplicates resolve --title
  zotio items duplicates resolve --doi --title --yes --allow-destructive

zotio items enrich [flags]

zotio items file <itemKey>

# Path of an item's PDF
  zotio items file ABCD2345

  # JSON envelope (item key, resolved attachment key, url, path)
  zotio items file ABCD2345 --json

zotio items find [flags]

zotio items find --doi 10.1145/3290605.3300709
  zotio items find --isbn 978-0-262-03384-8
  zotio items find --url https://example.org/paper
  zotio items find --openalex W2741809807
  zotio items find --title "Attention Is All You Need"
  zotio items find --citekey smith2023 --json

zotio items fulltext <itemKey> [flags]

zotio items get <itemKey> [flags]

zotio items get ABCD2345

zotio items list [flags]

zotio items list --limit 20 --item-type journalArticle
  zotio items list --query "deep learning" --sort dateModified --direction desc

zotio items missing-pdf [flags]

zotio items move [itemKey...] [--to <collectionKey>] [--from <collectionKey>] [flags]

zotio items new --item-type <type> [flags]

zotio items note-template <itemKey> [flags]

zotio items note-template ABCD2345
  zotio items note-template ABCD2345 --format obsidian
  zotio items note-template ABCD2345 --format logseq --json

zotio items open <key> [flags]

zotio items preprint-check [flags]

zotio items preprint-check fix [flags]

zotio items recent [flags]

zotio items related <itemKey>

zotio items related ABCD2345
  zotio items related ABCD2345 --json

zotio items restore <itemKey>

zotio items retract-check [flags]

zotio items similar <itemKey> [flags]

zotio items similar ABCD2345
  zotio items similar ABCD2345 --limit 5 --min-score 0.2 --json

zotio items stale [flags]

zotio items summarize [<itemKey>] [flags]

zotio items summarize 9UXV5R7L
  zotio items summarize 9UXV5R7L --agent --max-chars 6000
  zotio items summarize --collection MAR7RFQN --no-fulltext
  zotio items summarize --scope tag:to-read --agent
  zotio items summarize --scope collection:MAR7RFQN --focus "transfer learning" --max-chars 2000

zotio items tags [itemKey]

zotio items tags list ABC12345

zotio items tags add --tag <tag> [itemKeys...] [flags]

zotio items tags list <itemKey>

zotio items tags list ABC12345

zotio items tags remove --tag <tag> [itemKeys...] [flags]

zotio items top [flags]

zotio items top --limit 20 --item-type journalArticle

zotio items trash [flags]

zotio items trash

zotio items unfiled [flags]

zotio items unfiled --suggest --json
  zotio items unfiled --suggest --suggest-limit 5 --item-type book
  # File every item whose best suggestion is collection ABCD2345 (preview; add --yes to apply)
  zotio items unfiled --suggest --json | jq '[.results[] | select(.suggestions[0].collection == "ABCD2345")]' | zotio items move --keys-from - --to ABCD2345

zotio items update <itemKey> [flags]

zotio items update ABCD1234 --title "Updated title"

zotio items venues [flags]

zotio items venues
  zotio items venues --limit 10
  zotio items venues --item-type journalArticle --json

zotio journal

zotio journal list [flags]

zotio journal show <run-id>

zotio journal undo <run-id>

zotio library

zotio library health [flags]

zotio library prisma [flags]

zotio library stats [flags]

zotio library wrapped [flags]

zotio profile

zotio profile delete <name>

zotio profile delete my-defaults --yes
  zotio profile delete old-profile --yes --json

zotio profile list

zotio profile list
  zotio profile list --json

zotio profile save <name> [--<flag> <value> ...] [flags]

zotio profile save my-defaults --json --compact
  zotio profile save tonight-defaults --data-source local

zotio profile show <name>

zotio profile show my-defaults
  zotio profile show tonight-defaults --json

zotio profile use <name>

zotio profile use my-defaults
  zotio profile use tonight-defaults --json

zotio reading-list [flags]

zotio reading-list add <itemKeys...|--keys-from F> [flags]

zotio reading-list done <itemKeys...|--keys-from F> [flags]

zotio reading-list start <itemKeys...|--keys-from F> [flags]

zotio schema

zotio schema creator-fields

zotio schema creator-fields

zotio schema drift [flags]

# Capture a baseline on the current Zotero version
  zotio schema drift

  # After upgrading Zotero, see what changed
  zotio schema drift

  # Include live per-item-type field/creator validity
  zotio schema drift --deep

  # Use an explicitly synced deep snapshot instead
  zotio schema drift --deep --db ./data.db

  # Re-baseline to the current schema
  zotio schema drift --update

zotio schema item-fields

zotio schema item-fields

zotio schema item-type-creator-types [flags]

zotio schema item-type-creator-types --item-type journalArticle

zotio schema item-type-fields [flags]

zotio schema item-type-fields --item-type journalArticle

zotio schema item-types

zotio schema item-types

zotio schema new-item-template [flags]

zotio schema new-item-template --item-type journalArticle

zotio search <query> [flags]

# Search (uses API endpoint if available, local FTS otherwise)
  zotio search "error timeout"

  # Force local search only
  zotio search "payment failed" --data-source local

  # Resolve synced PDF full-text matches to their parent items
  zotio search "calibration feedback" --fulltext --data-source local

  # Search PDF text only inside one collection
  zotio search "calibration feedback" --fulltext --scope collection:ABCD1234 --limit 5

  # JSON output for piping
  zotio search "critical" --json --limit 20

zotio searches

zotio searches get <searchKey>

zotio searches get ABCD2345

zotio searches list [flags]

zotio searches list

zotio searches materialize <searchKey> --to <collectionKey> [--prune] [flags]

zotio searches run <searchKey>

zotio searches run ABCD2345

zotio sync [flags]

# Sync all resources
  zotio sync

  # Sync specific resources only
  zotio sync --resources collections,items

  # Cache per-item-type field validity (one request per cached item type)
  zotio sync --resources schema-item-type-fields

  # Full resync (ignore previous checkpoint)
  zotio sync --full

  # Incremental sync: only objects modified since a Zotero library version
  zotio sync --since-version 4521

  # Parallel sync with 8 workers
  zotio sync --concurrency 8

  # Latest-only: refresh head of each resource, no historical backfill
  zotio sync --latest-only

zotio tags

zotio tags audit [flags]

zotio tags audit
  zotio tags audit --json
  zotio tags audit --prefer title

zotio tags audit fix [flags]

zotio tags audit fix --yes
  zotio tags audit fix --prefer title --yes
  zotio tags audit --json | zotio tags audit fix --keys-from - --yes

zotio tags get <tagName>

zotio tags get "machine learning"

zotio tags inventory [flags]

zotio tags list [flags]

zotio tags list --query machine --limit 20

zotio tags rename --from <oldTag> --to <newTag> [flags]

zotio tail [resource] [flags]

# Tail item changes every 10 seconds
  zotio tail items --interval 10s

  # Tail a specific resource
  zotio tail collections --interval 5s

  # Pipe to jq for filtering
  zotio tail items --interval 30s | jq 'select(.event == "upsert")'

zotio vault

zotio vault audit [--vault <dir>] [flags]

zotio vault conflicts [--vault <dir>] [flags]

zotio vault pull [--vault <dir>] [flags]

zotio vault pull --dry-run
  zotio vault pull --yes
  zotio vault pull --yes --vault ~/vault/refs

zotio vault push [--vault <dir>] [flags]

zotio vault push --dry-run
  zotio vault push --yes --vault ~/vault/refs

zotio vault resolve <citekey-or-item-key> (--keep-vault | --keep-remote) [--vault <dir>] [flags]

zotio vault resolve smith2024 --keep-vault
  zotio vault resolve smith2024 --keep-vault --yes
  zotio vault resolve smith2024 --keep-remote --yes

zotio vault sync [--vault <dir>] [flags]

zotio vault sync                 # uses [vault] root/notes_dir from config
  zotio vault sync --vault ~/vault/refs --yes
  zotio vault sync --vault ~/vault/refs --collection ABCD2345 --dry-run
  zotio vault sync --vault ~/vault/refs --scope query:transformer --dry-run

zotio version

zotio watch [resource...] [flags]

zotio which [query] [flags]

zotio which "export bibtex for a collection"
  zotio which "find papers missing PDFs"
  zotio which --limit 1 "undo that Zotero change"
  zotio which                                # list the full capability index

zotio workflow

zotio workflow archive [flags]

# Incremental sync of the default resources; a failed resource exits non-zero
  zotio workflow archive

  # Full resync, the same as zotio sync --full --strict
  zotio workflow archive --full

zotio workflow run <file.json> [flags]

zotio workflow run workflow.json
  zotio workflow run workflow.json --var PROJECT=demo
  zotio workflow run workflow.json --yes
  zotio workflow run workflow.json --yes --resume
  {"steps":[{"name":"diagnose","args":["library","health","--json"]},{"name":"fix","args":["items","enrich","--keys-from","-"],"stdin_from":"diagnose"}]}

zotio workflow status [flags]

# Show archive status
  zotio workflow status

  # Show status as JSON
  zotio workflow status --json