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.

Global flags¶

These flags are available on every command.

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¶

Run analytics queries on locally synced data

Analyze locally synced data with count, group-by, and summary operations. Data must be synced first with the sync command.

zotio analytics [flags]

Examples:

# Count records by type
  zotio analytics --type messages

  # Group by a field
  zotio analytics --type messages --group-by author_id

  # Top 10 most frequent values
  zotio analytics --type messages --group-by channel_id --limit 10 --json

zotio annotations¶

Search and export annotations from your Zotero library

zotio annotations

zotio annotations export¶

Export annotations as markdown or JSON

zotio annotations export [flags]

zotio annotations search¶

Search annotations by text

zotio annotations search <query> [flags]

zotio annotations timeline¶

List annotations sorted by creation date

zotio annotations timeline [flags]

Examples:

zotio annotations timeline --limit 50
  zotio annotations timeline --since 2024-01-01
  zotio annotations timeline --item ABCD1234 --json

zotio auth¶

Manage authentication for Zotero

zotio auth

zotio auth logout¶

Clear stored credentials

zotio auth logout

Examples:

zotio auth logout

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) so agents can select safe commands and pre-flight requirements without parsing --help or guessing from names.

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

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.

zotio collections bundle <collectionKey> [flags]

zotio collections create¶

Create one or more collections

zotio collections create [flags]

Examples:

zotio collections create --name example-resource

zotio collections delete¶

Delete a collection (does not delete items)

zotio collections delete <collectionKey>

Examples:

zotio collections delete COLLECTIONKEY

zotio collections export¶

Export a collection (and subcollections) as BibTeX, RIS, or CSL-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.

zotio collections export <collectionKey> [flags]

Examples:

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

  # Export as RIS to a file
  zotio collections export ABCD1234 --format ris --output refs.ris

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

zotio collections gaps¶

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

zotio collections gaps <collectionKey> [flags]

zotio collections get¶

Get a specific collection

zotio collections get <collectionKey>

Examples:

zotio collections get COLLECTIONKEY

zotio collections items¶

List all items in a collection

zotio collections items <collectionKey> [flags]

Examples:

zotio collections items COLLECTIONKEY

zotio collections list¶

List all collections

zotio collections list [flags]

Examples:

zotio collections list

zotio collections move¶

Move a collection under a new parent

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

zotio collections stats¶

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

zotio collections stats <collectionKey> [flags]

zotio collections subcollections¶

List subcollections of a collection

zotio collections subcollections <collectionKey>

Examples:

zotio collections subcollections COLLECTIONKEY

zotio collections tags¶

List tags used within a collection

zotio collections tags <collectionKey>

Examples:

zotio collections tags COLLECTIONKEY

zotio collections top¶

List only top-level collections (no parents)

zotio collections top [flags]

Examples:

zotio collections top

zotio collections update¶

Update a collection

zotio collections update <collectionKey> [flags]

Examples:

zotio collections update COLLECTIONKEY

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. 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:

zotio creators audit fix
  zotio creators audit fix --map "J. Smith=John Smith"
  zotio creators audit fix --scope collection:ABCD1234 --yes

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 sandbox is a self-contained SQLite database (demo.db) beside your real store. Set ZOTIO_DEMO=1 on any command to read from it with a pristine, key-less config -- your real library, config, and API key are never touched. No Zotero desktop and no API key are required.

zotio demo [flags]

zotio doctor¶

Check CLI health

zotio doctor [flags]

Examples:

zotio doctor
  zotio doctor --json
  zotio doctor --fail-on warn

zotio export¶

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

Export paginated API data to a local file. Supports JSONL (one JSON object per line, streaming-friendly) and JSON (array). JSONL is recommended for large datasets as it has no memory pressure.

zotio export <resource> [id] [flags]

Examples:

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

  # Export with limit
  zotio export <resource> --format jsonl --limit 1000

  # Pipe to another tool
  zotio export <resource> --format jsonl | jq '.id'

zotio export snapshot¶

Reproducible, resumable paginated export with a content lockfile

Export a structured item set (JSONL) across all pages into a data file, plus a sidecar lockfile (

.lock.json) recording each item's key+version and a content hash for reproducibility/drift detection. Resumable: an interrupted run can continue with --resume (a

.checkpoint.json sidecar tracks progress).

Scope is one of: library (default), collection:KEY, or tag:NAME.

zotio export snapshot [scope] [flags]

Examples:

zotio export snapshot --output backup.jsonl
  zotio export snapshot collection:ABCD1234 --output coll.jsonl
  zotio export snapshot --output backup.jsonl --resume

zotio export snapshot verify¶

Verify a snapshot lockfile against the current library

Verify a snapshot lockfile against the current Zotero library.

The verifier re-resolves the lockfile scope when possible, recomputes the same content hash as export snapshot, and separates semantic drift (added, removed, changed) from Zotero version churn (touched). Touched items have a newer version but identical normalized content and never fail --fail-on-drift.

zotio export snapshot verify <lockfile.lock.json> [flags]

Examples:

zotio export snapshot verify backup.jsonl.lock.json
  zotio export snapshot verify backup.jsonl.lock.json --fail-on-drift
  zotio export snapshot verify backup.jsonl.lock.json --json

zotio feedback¶

Record feedback about this CLI (local by default; upstream opt-in)

Feedback is captured locally first at ~/.zotio/feedback.jsonl. When ZOTERO_FEEDBACK_ENDPOINT is set and either --send is passed or ZOTERO_FEEDBACK_AUTO_SEND=true, the entry is POSTed as JSON after the local write.

Write what surprised you or tripped you up, not a bug report. The loop is: agent notices friction -> one invocation -> captured -> the maintainer sees it.

zotio feedback [text] [flags]

zotio feedback list¶

List recent feedback entries

zotio feedback list [flags]

Examples:

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

zotio groups¶

Discover Zotero group libraries you can access

zotio groups

zotio groups inspect¶

Check whether a Zotero group library is accessible and writable

zotio groups inspect <group-id>

zotio groups list¶

List the group libraries the configured user belongs to

zotio groups list

Examples:

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¶

Import data from JSONL file via API create/upsert calls

Import data from a JSONL file by issuing POST requests for each record. Each line must be a valid JSON object. Failed records are logged to stderr but do not stop the import.

zotio import <resource> [flags]

Examples:

# Import from a JSONL file
  zotio import <resource> --input data.jsonl

  # Dry-run to preview without sending
  zotio import <resource> --input data.jsonl --dry-run

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

zotio import apply¶

Apply a reviewed import manifest

zotio import apply <manifest> [flags]

zotio import arxiv¶

Import a preprint from arXiv metadata

zotio import arxiv <id> [flags]

zotio import discover¶

Discover missing references and write a reviewable import manifest

zotio import discover [flags]

zotio import doi¶

Import an item from CrossRef DOI metadata

zotio import doi <doi> [flags]

zotio import file¶

Import items from BibTeX, RIS, or CSL JSON

zotio import file <path> [flags]

zotio import isbn¶

Import a book from Open Library ISBN metadata

zotio import isbn <isbn> [flags]

zotio import pdf¶

Create items from PDFs using Zotero desktop recognition

Create Zotero items from local PDF files by asking the Zotero desktop Connector API to save each PDF as a standalone attachment and run Zotero's metadata recognizer.

This command requires a local Zotero base URL, Zotero running, and Zotero's local API preference enabled. Recognition failures are reported as unrecognized standalone PDF attachments instead of hard errors.

zotio import pdf <path...>

zotio import pmid¶

Import a journal article from PubMed metadata

zotio import pmid <pmid> [flags]

zotio import resolve¶

Resolve PDFs into an editable import manifest

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

zotio import scan¶

Triage a folder of PDFs against your library (read-only): new vs duplicate vs attach-candidate

Scan a directory of PDFs and classify each against your synced library WITHOUT importing anything. For each PDF it extracts a DOI (from the filename, then the file's embedded metadata) and reports:

duplicate the DOI already belongs to an item in your library attach_candidate matches an item you have that is missing its PDF new not in your library (use 'import doi ' to add it) unidentified no DOI found (rename the file with its DOI, or add it in Zotero)

This complements Zotero's "Retrieve Metadata for PDF": it makes the library-aware decision the GUI does not — which PDFs to import, which are duplicates, and which complete items you already have. It never writes; hand the actual import and file attach to Zotero.

DOI extraction is dependency-free: it reads the filename and the PDF's uncompressed embedded metadata (Info/XMP). It does NOT decode compressed page text, so scanned or text-only PDFs may report "unidentified".

zotio import scan <dir> [flags]

Examples:

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

zotio import targets¶

List Zotero desktop Connector save targets

List Zotero desktop Connector save targets for connector-backed imports. Use the id column (for example C78) with --connector-target when --collection is ambiguous or the local Web API collection key cannot be mapped automatically.

zotio import targets

zotio import translators¶

Detect Zotero desktop translators for a URL

Fetch a page and ask Zotero desktop which web translators match it.

This is diagnostic-only: Zotero's desktop connector can detect matching web translators, but browser-side web translation is not run by the desktop server.

zotio import translators <url>

zotio import url¶

Import a URL as a metadata-enriched item

Import a URL, resolving real metadata where possible.

If the URL embeds a DOI, full metadata is fetched from CrossRef. Otherwise the page's embedded metadata (citation_*, Open Graph, Dublin Core meta tags) is mapped into a typed item with title, creators, abstract, and publication venue. A bare webpage item is used only when no metadata is available.

Use --dry-run to preview the proposed item without writing it.

zotio import url <url> [flags]

zotio init¶

Guided first-run setup using doctor, auth, sync, and health checks

Guided first-run setup for Zotero automation.

Checks the local Zotero API, stores an API key when one is provided interactively, runs the first local sync when the store is missing or empty, and finishes with the quick library-health preset plus suggested next commands.

zotio init [flags]

zotio items¶

Manage items in your Zotero library

zotio items

zotio items annotations¶

List annotation children for an item

zotio items annotations <itemKey> [flags]

zotio items audit¶

Audit locally synced items for missing metadata and PDFs

zotio items audit [flags]

zotio items authors¶

Count synced items per creator

zotio items authors [flags]

zotio items bibcheck¶

Check manuscript citation keys against the synced Better BibTeX library

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

Examples:

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 bibliography¶

Render a formatted bibliography for a scoped item selection

Render a formatted bibliography for items selected with the shared scope grammar.

The bibliography is rendered by Zotero's Web API CSL renderer so named styles such as apa, chicago, mla, nature, and journal-specific CSL IDs are honored. The Web API limits itemKey batches, so large scopes are fetched in stable 50-key chunks and concatenated in scope order.

zotio items bibliography [flags]

Examples:

zotio items bibliography --scope collection:ABCD1234 --style apa
  zotio items bibliography --scope tag:to-submit --style nature
  zotio items bibliography --scope item:ABCD1234 --json

zotio items children¶

Get child items (attachments and notes) for an item

zotio items children <itemKey> [flags]

Examples:

zotio items children ABC12345

zotio items cite¶

Get a formatted citation for an item

Retrieve a formatted bibliographic citation for an item. The Zotero local API renders citations using your installed CSL styles. For the most common styles (apa, chicago, mla), use the --style flag. For others, pass the CSL style ID directly (e.g. "nature", "harvard-cite-them-right").

zotio items cite <itemKey> [flags]

Examples:

zotio items cite ABCD1234
  zotio items cite ABCD1234 --style apa
  zotio items cite ABCD1234 --style bibtex

zotio items citekey-conflicts¶

Find missing and duplicate Better BibTeX citation keys

zotio items citekey-conflicts [flags]

Examples:

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

zotio items collections-of¶

Show collections containing an item

zotio items collections-of <itemKey>

zotio items create¶

Create one or more items

zotio items create [flags]

Examples:

zotio items create

zotio items delete¶

Delete an item (moves to trash)

zotio items delete <itemKey>

Examples:

zotio items delete ABC12345

zotio items duplicates¶

Find likely duplicate items in the local store

zotio items duplicates [flags]

zotio items duplicates resolve¶

Resolve duplicate items by merging metadata onto a master and trashing duplicates

Resolve duplicate items by merging metadata onto a master and trashing duplicates.

By default, resolve only matches duplicate DOI groups. Title matching can group distinct items that share generic titles; pass --title only when you are ready to review the preview carefully before applying.

zotio items duplicates resolve [flags]

Examples:

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

zotio items enrich¶

Fill or validate item metadata (DOI, abstract, open-access PDF link) from CrossRef, OpenAlex, Semantic Scholar, Unpaywall, and OpenCitations

Resolve missing metadata for locally synced items and apply it back to Zotero.

Work queues come from the same checks as 'items audit': --missing-doi resolve a DOI by title from CrossRef, then OpenAlex/Semantic Scholar (exact title match) --missing-abstract fill the abstract from CrossRef, then OpenAlex/Semantic Scholar (requires the item's DOI) --missing-pdf attach an open-access PDF link from Unpaywall (requires DOI)

By default this previews the proposed changes (a patch plan). Pass --collection to scope the work queue to items in a single collection, or --keys-from to scope to exact item keys produced by another command. Pass --yes to apply them via the Zotero API; --dry-run always previews. Applied field changes record provenance in the item's Extra field.

zotio items enrich [flags]

zotio items file¶

Resolve the on-disk path (file:// URL) of an item's attachment

Return the local filesystem location of an item's attachment via the Zotero local API (/items//file/view/url). Accepts an attachment key directly, or a regular item key whose PDF attachment is resolved automatically through its child items.

This complements 'items open' (which launches the Zotero desktop app): 'items file' hands you the actual file so an agent or script can read or process it. The local API must be enabled (Settings → Advanced → "Allow other applications…").

zotio items file <itemKey>

Examples:

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

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

zotio items find¶

Find locally synced items by DOI, ISBN, PMID, or citation key

zotio items find [flags]

Examples:

zotio items find --doi 10.1145/3290605.3300709
  zotio items find --isbn 978-0-262-03384-8
  zotio items find --citekey smith2023 --json

zotio items fulltext¶

Get full text from an item's PDF attachment

zotio items fulltext <itemKey> [flags]

zotio items get¶

Get a single item by key

zotio items get <itemKey> [flags]

Examples:

zotio items get ABCD1234

zotio items list¶

List all items in the library

zotio items list [flags]

Examples:

zotio items list

zotio items missing-pdf¶

List items that should have an attached PDF but do not

zotio items missing-pdf [flags]

zotio items move¶

Add, remove, or move item collection memberships

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

zotio items new¶

Create a schema-validated item from Zotero's blank item template

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

zotio items note-template¶

Generate a markdown reading-note template for an item

zotio items note-template <itemKey> [flags]

Examples:

zotio items note-template ABCD1234
  zotio items note-template ABCD1234 --format obsidian
  zotio items note-template ABCD1234 --format logseq

zotio items open¶

Print or launch a Zotero desktop deep link (item, collection, or PDF)

Build a zotero:// desktop deep link for an item (default), a collection (--type collection), or a PDF attachment (--type attachment), then print it or launch it (--launch) via the OS handler (open on macOS, xdg-open on Linux, rundll32 on Windows).

The link targets the personal library by default, or a group library when the global --group flag (or ZOTERO_GROUP) is set. With --agent/--json the command emits {uri, target_type, library_scope, launched}.

zotio items open <key> [flags]

zotio items preprint-check¶

Check arXiv preprints for published CrossRef records

zotio items preprint-check [flags]

zotio items preprint-check fix¶

Apply published DOIs to preprints that CrossRef reports as published

zotio items preprint-check fix [flags]

zotio items recent¶

List recently added items

zotio items recent [flags]

zotio items related¶

Show outgoing and incoming Zotero related-item edges

zotio items related <itemKey>

Examples:

zotio items related ABC12345
  zotio items related ABC12345 --json

zotio items restore¶

Restore a trashed item

zotio items restore <itemKey>

zotio items retract-check¶

Check DOI-bearing local items for CrossRef retraction notices

Check DOI-bearing items from the locally synced store against CrossRef's updated-by metadata. The command reports retractions, expressions of concern, and corrections without writing to Zotero. Run 'zotio sync' first so the local store is current.

zotio items retract-check [flags]

zotio items stale¶

Find old items without PDFs or annotations

zotio items stale [flags]

zotio items summarize¶

Assemble a bounded, synthesis-ready context bundle for an item or collection

Gather the highest-signal local context for an item (or every item in a collection) into one bounded bundle — citation, abstract, your annotations, a capped fulltext excerpt, and known metadata gaps — plus a synthesis prompt.

This command never calls a model: it does the assembly and budgeting the host LLM is bad at, then hands off. Reads are local only. With --agent/--json it emits the structured bundle; otherwise a readable Markdown brief you can paste into any LLM.

zotio items summarize [<itemKey>] [flags]

Examples:

zotio items summarize 9UXV5R7L
  zotio items summarize 9UXV5R7L --agent --max-chars 6000
  zotio items summarize --collection MAR7RFQN --no-fulltext

zotio items tags¶

Get or manage tags for a specific item

zotio items tags [itemKey]

Examples:

zotio items tags list ABC12345

zotio items tags add¶

Add one or more tags to items

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

zotio items tags list¶

Get tags for a specific item

zotio items tags list <itemKey>

Examples:

zotio items tags list ABC12345

zotio items tags remove¶

Remove one or more tags from items

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

zotio items top¶

List top-level items only (excludes attachments and notes)

zotio items top [flags]

Examples:

zotio items top

zotio items trash¶

List items in the trash

zotio items trash [flags]

Examples:

zotio items trash

zotio items unfiled¶

List top-level items not assigned to any collection

zotio items unfiled [flags]

zotio items update¶

Update a specific item

zotio items update <itemKey> [flags]

Examples:

zotio items update ABCD1234 --title "Updated title"

zotio items venues¶

Count synced items by publication venue

zotio items venues [flags]

Examples:

zotio items venues
  zotio items venues --top 10
  zotio items venues --type journalArticle --json

zotio journal¶

Inspect the mutation run journal (applied write history)

zotio journal

zotio journal list¶

List recorded mutation runs, newest first

zotio journal list

zotio journal show¶

Show the operations recorded for one mutation run

zotio journal show <run-id>

zotio journal undo¶

Reverse a recorded run's reversible (tag/collection) changes

zotio journal undo <run-id>

zotio library¶

Library-wide analytics and reporting

zotio library

zotio library health¶

Composite read-only library health report with a CI gate

Run a ranked, finding-typed health report over the locally synced library.

Composes the existing audit primitives (citekey conflicts, duplicates, missing metadata, tag drift, broken attachments) into one report. Pick what "ready" means with --for:

--for citation manuscript/bibliography readiness (citekeys, core fields, duplicates) --for systematic-review PRISMA screening corpus (duplicates, screenable metadata, full text) --for quick (default) anything obviously broken (citekey conflicts, duplicates, attachments) --for all every check

Gate CI with --fail-on critical|high|info (or legacy any) (exit 11 when the bar is not met).

The broken-attachment and retraction checks are live checks that need Zotero desktop or CrossRef network access respectively; pass --verify-files and/or --check-retractions to run them. When a gate-relevant check can't run because its precondition is unmet, the command refuses loudly (exit 9) rather than passing.

zotio library health [flags]

zotio library stats¶

Show library-wide local statistics

zotio library stats [flags]

zotio library wrapped¶

Show a local year-in-review for your Zotero library

zotio library wrapped [flags]

zotio profile¶

Named sets of flags saved for reuse

Profiles capture a set of flag values under a name so a scheduled agent can invoke the same command with the same configuration each run.

profile save captures the current invocation's set flags profile use prints the values (for inspection) profile list lists all saved profiles profile show shows the values of one profile profile delete removes a profile

Use --profile on any command to apply that profile's values. Explicit flags override profile values.

zotio profile

zotio profile delete¶

Remove a profile

zotio profile delete <name>

Examples:

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

zotio profile list¶

List saved profiles

zotio profile list

Examples:

zotio profile list
  zotio profile list --json

zotio profile save¶

Save the current invocation's non-default flags as a named profile

Captures every flag explicitly set on the invocation and stores them under . To update an existing profile, run save again; the entry is replaced.

To avoid creating empty profiles, at least one non-default flag must be present (other than --profile and --config).

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

Examples:

zotio profile save my-defaults --json --compact
  zotio profile save tonight-defaults --region US

zotio profile show¶

Show a profile's values as JSON

zotio profile show <name>

Examples:

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

zotio profile use¶

Print the flag values a profile will apply (does not execute anything)

zotio profile use <name>

Examples:

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

zotio reading-list¶

Show the Zotero reading queue

zotio reading-list [flags]

zotio reading-list add¶

Add items to the reading queue

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

zotio reading-list done¶

Mark reading items as read

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

zotio reading-list start¶

Move queued items into the reading state

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

zotio schema¶

Zotero item type and field schema

zotio schema

zotio schema creator-fields¶

List all creator fields (firstName, lastName, name)

zotio schema creator-fields

Examples:

zotio schema creator-fields

zotio schema drift¶

Detect Zotero schema changes (new/removed item types and fields) vs a saved baseline

Capture a baseline fingerprint of the running Zotero's item-type and field schema, then on later runs report what changed. Use this after upgrading Zotero to see which item types, fields, or creator fields a new version added or removed — the deltas the CLI may not yet model.

The first run captures the baseline. Re-run after an upgrade to see drift. Pass --update to adopt the current live schema as the new baseline. The baseline is stored at ~/.local/share/zotio/schema-baseline.json (override with --baseline) and is shared across libraries because the schema is global to the Zotero install.

zotio schema drift [flags]

Examples:

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

  # After upgrading Zotero, see what changed
  zotio schema drift

  # Include per-item-type field/creator validity (many extra API calls)
  zotio schema drift --deep

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

zotio schema item-fields¶

List all available item fields

zotio schema item-fields

Examples:

zotio schema item-fields

zotio schema item-type-creator-types¶

List valid creator types for an item type

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

Examples:

zotio schema item-type-creator-types --item-type example-value

zotio schema item-type-fields¶

List valid fields for a specific item type

zotio schema item-type-fields [flags]

Examples:

zotio schema item-type-fields --item-type example-value

zotio schema item-types¶

List all available Zotero item types

zotio schema item-types

Examples:

zotio schema item-types

zotio schema new-item-template¶

Get a blank template for creating a new item of a given type

zotio schema new-item-template [flags]

Examples:

zotio schema new-item-template --item-type example-value

zotio search¶

Full-text search across synced data or live API

Search data using FTS5 full-text search on locally synced data, or hit the API's search endpoint when available.

In auto mode (default): uses the API search endpoint if the API has one, otherwise searches local data. Falls back to local on network failure. In live mode: uses the API search endpoint only. In local mode: searches locally synced data only.

zotio search <query> [flags]

Examples:

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

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

  # Search a specific resource type locally
  zotio search "critical" --type transactions --data-source local

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

zotio searches¶

Manage saved searches in your Zotero library

zotio searches

zotio searches get¶

Get a specific saved search

zotio searches get <searchKey>

Examples:

zotio searches get SEARCHKEY

zotio searches list¶

List all saved searches

zotio searches list [flags]

Examples:

zotio searches list

zotio searches materialize¶

Add items from a saved search to a collection

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

zotio searches run¶

Run a saved Zotero search when the API exposes results

zotio searches run <searchKey>

zotio sync¶

Sync API data to local SQLite for offline search and analysis

Sync data from the API into a local SQLite database. Supports resumable incremental sync (only fetches new data since last sync) and full resync. Once synced, use the 'search' command for instant full-text search.

Exit codes & warnings: Resources the API denies access to (HTTP 403, or HTTP 400 with an access-policy body) are reported as warnings rather than failing the run. In --json mode each is emitted as a {"event":"sync_warning",...} line carrying status, reason, and message fields, and a final {"event":"sync_summary",...} aggregates the run.

Exit 0 when at least one resource synced and no resource flagged in the spec as critical (x-critical: true) failed. Pass --strict to exit non-zero on any per-resource failure. Exit is always non-zero when every selected resource failed, regardless of --strict.

zotio sync [flags]

Examples:

# Sync all resources
  zotio sync

  # Sync specific resources only
  zotio sync --resources channels,messages

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

  # Incremental sync: only objects modified since a Zotero library version
  zotio sync --since 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¶

Manage tags across your Zotero library

zotio tags

zotio tags audit¶

Audit tags for case and spacing drift

zotio tags audit

Examples:

zotio tags audit
  zotio tags audit --json

zotio tags audit fix¶

Apply the tag rename plan produced by tags audit

zotio tags audit fix

zotio tags get¶

Get a specific tag by name

zotio tags get <tagName>

Examples:

zotio tags get example-resource

zotio tags inventory¶

Show tag usage within collections and across the library

zotio tags inventory [flags]

zotio tags list¶

List all tags in the library

zotio tags list [flags]

Examples:

zotio tags list

zotio tags rename¶

Rename a tag across matching items

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

zotio tail¶

Stream live changes by polling the API at regular intervals

Tail streams live data changes by polling the API at configurable intervals. Events are emitted as NDJSON to stdout for piping to other tools. Gracefully shuts down on SIGTERM/SIGINT.

Note: For APIs with WebSocket or SSE support, a future version will use native streaming instead of polling.

zotio tail [resource] [flags]

Examples:

# Tail all changes every 10 seconds
  zotio tail --interval 10s

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

  # Pipe to jq for filtering
  zotio tail events --interval 30s | jq 'select(.type == "error")'

zotio vault¶

Sync the library into an Obsidian/Logseq Markdown vault

zotio vault

zotio vault audit¶

Audit managed vault notes without writing

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

zotio vault conflicts¶

List unresolved Zotero note write-back conflicts

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

zotio vault pull¶

Bring remote Zotero child-note edits into the "## Notes" region (fast-forward)

Pull edits made to a managed Zotero child note back into the vault note's "## Notes" region. This is fast-forward only: a note is updated only when its local region is unchanged since the last sync. If both the local region and the remote note changed, it is reported as a conflict and nothing is merged or overwritten (resolve by hand, or 'vault resolve --keep-vault' to keep the vault copy). Only notes in the shape this CLI writes are pulled.

Use --dry-run to preview without writing to the vault.

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

Examples:

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

zotio vault push¶

Write each note's "## Notes" region back to a Zotero child note

Push the user-owned Notes region of each vault note to a single managed Zotero child note (Obsidian -> Zotero). Reads stay local; writes go to the Web API (an api_key must be configured). Idempotent and conflict-safe: a note is only written when its Notes region changed since the last push, the remote note body is checked first, and a divergent remote is never overwritten — a conflict artifact is written under _vault-zotero-conflicts/ and reported instead.

Use --dry-run to preview create/update/conflict without writing anything.

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

Examples:

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

zotio vault resolve¶

Resolve a note write-back conflict by keeping the vault or the remote copy

Resolve a conflict (or a remotely-deleted note) by choosing a direction:

--keep-vault writes the vault's Notes region over the Zotero child note, using the live remote version as the precondition. --recreate re-creates a child note that was deleted in Zotero.

--keep-remote does the reverse: it pulls the live Zotero note body over the vault Notes region, discarding local edits (a forced 'vault pull'). Only notes in the shape this CLI writes are pulled.

Exactly one direction is required so the destructive side is explicit; the resolved conflict artifact is removed on success.

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

Examples:

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

zotio vault sync¶

Create/update one Markdown note per item in a vault (idempotent)

Materialize literature notes into an Obsidian or Logseq vault from the local store (run 'sync' first). Notes are named from the citation key, carry zotero:// backlinks, and embed current annotations in a managed block.

Re-running is idempotent and non-destructive: only the managed frontmatter keys and the fenced annotations block change; your prose and other frontmatter keys are preserved. Use --dry-run to preview create/update/unchanged without writing.

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

Examples:

zotio vault sync                 # uses [vault] root/notes_dir from config
  zotio vault sync --out ~/vault/refs
  zotio vault sync --out ~/vault/refs --collection ABCD1234 --dry-run

zotio version¶

Print version

zotio version

zotio watch¶

Keep the local store fresh with periodic incremental syncs

Watch keeps the local store fresh by running incremental sync cycles on

a configurable interval. It starts with an immediate sync, logs one concise status line per cycle to stderr, and exits gracefully on SIGINT or SIGTERM.

zotio watch [resource...] [flags]

zotio which¶

Find the command that implements a capability

which resolves a natural-language capability query (for example, "search messages" or "stale tickets") to the best matching command from this CLI's curated feature index.

Exit codes: 0 at least one match found 2 no confident match - the query did not score against any indexed capability; fall back to '--help' or 'search' if this CLI has one

zotio which [query] [flags]

Examples:

zotio which "stale tickets"
  zotio which "bottleneck"
  zotio which --limit 1 "send message"
  zotio which                                # list the full capability index

zotio workflow¶

Compound workflows that combine multiple API operations

zotio workflow

zotio workflow archive¶

Sync all resources to local store for offline access and search

Archive fetches all syncable resources from the API and stores them in a local SQLite database. Supports incremental sync (only new data since last run) and full resync. After archiving, use 'search' for instant full-text search.

zotio workflow archive [flags]

Examples:

# Archive all resources
  zotio workflow archive

  # Full re-archive (ignore previous sync state)
  zotio workflow archive --full

zotio workflow run¶

Run a declarative workflow spec in-process

zotio workflow run <file.json>

zotio workflow status¶

Show local archive status and sync state for all resources

zotio workflow status [flags]

Examples:

# Show archive status
  zotio workflow status

  # Show status as JSON
  zotio workflow status --json