Skills › Scientific Agent Skills › pyzotero › cli.md

cli.md

121 lines · skills/pyzotero/references/cli.md at 5f2bc03

1# Command-Line Interface

3The pyzotero CLI connects to your **local Zotero installation** (Zotero 7+ for reads, Zotero 10+ for writes) (not the remote Web API). It requires a running Zotero desktop app with local API access enabled:

5**Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero**

Command-Line Interface

The pyzotero CLI connects to your local Zotero installation (Zotero 7+ for reads, Zotero 10+ for writes) (not the remote Web API). It requires a running Zotero desktop app with local API access enabled:

Zotero → Settings → Advanced → Allow other applications on this computer to communicate with Zotero

Raw lines 1 to 6

7## Installation

9```bash

10uv add "pyzotero[cli]==1.15.2"

11# or run without installing:

12uvx --from "pyzotero[cli]==1.15.2" pyzotero search -q "your query"

13```

Installation

uv add "pyzotero[cli]==1.15.2"
# or run without installing:
uvx --from "pyzotero[cli]==1.15.2" pyzotero search -q "your query"

Raw lines 7 to 14

15## Searching

17```bash

18# Search titles and metadata

19pyzotero search -q "machine learning"

21# Full-text search (includes PDF content)

22pyzotero search -q "climate change" --fulltext

24# Filter by item type

25pyzotero search -q "methodology" --itemtype journalArticle --itemtype book

27# Filter by tags (AND logic)

28pyzotero search -q "evolution" --tag "reviewed" --tag "high-priority"

30# Search within a collection

31pyzotero search --collection ABC123 -q "test"

33# Paginate results

34pyzotero search -q "deep learning" --limit 20 --offset 40

36# Output as JSON (for machine processing)

37pyzotero search -q "protein" --json

38```

Searching

# Search titles and metadata
pyzotero search -q "machine learning"

# Full-text search (includes PDF content)
pyzotero search -q "climate change" --fulltext

# Filter by item type
pyzotero search -q "methodology" --itemtype journalArticle --itemtype book

# Filter by tags (AND logic)
pyzotero search -q "evolution" --tag "reviewed" --tag "high-priority"

# Search within a collection
pyzotero search --collection ABC123 -q "test"

# Paginate results
pyzotero search -q "deep learning" --limit 20 --offset 40

# Output as JSON (for machine processing)
pyzotero search -q "protein" --json

Raw lines 15 to 39

40## Getting Individual Items

42```bash

43# Get a single item by key

44pyzotero item ABC123

46# Get as JSON

47pyzotero item ABC123 --json

49# Get child items (attachments, notes)

50pyzotero children ABC123 --json

52# Get multiple items at once (up to 50)

53pyzotero subset ABC123 DEF456 GHI789 --json

54```

Getting Individual Items

# Get a single item by key
pyzotero item ABC123

# Get as JSON
pyzotero item ABC123 --json

# Get child items (attachments, notes)
pyzotero children ABC123 --json

# Get multiple items at once (up to 50)
pyzotero subset ABC123 DEF456 GHI789 --json

Raw lines 40 to 55

56## Collections & Tags

58```bash

59# List all collections

60pyzotero listcollections

62# List all tags

63pyzotero tags

65# Tags in a specific collection

66pyzotero tags --collection ABC123

67```

Collections & Tags

# List all collections
pyzotero listcollections

# List all tags
pyzotero tags

# Tags in a specific collection
pyzotero tags --collection ABC123

Raw lines 56 to 68

69## Full-Text Content

71```bash

72# Get full-text content of an attachment

73pyzotero fulltext ABC123

74```

Full-Text Content

# Get full-text content of an attachment
pyzotero fulltext ABC123

Raw lines 69 to 75

76## Item Types

78```bash

79# List all available item types

80pyzotero itemtypes

81```

Item Types

# List all available item types
pyzotero itemtypes

Raw lines 76 to 82

83## DOI Index

85```bash

86# Get complete DOI-to-key mapping (useful for caching)

87pyzotero doiindex > doi_cache.json

88# Returns JSON: {"10.1038/s41592-024-02233-6": {"key": "ABC123", "doi": "..."}}

89```

DOI Index

# Get complete DOI-to-key mapping (useful for caching)
pyzotero doiindex > doi_cache.json
# Returns JSON: {"10.1038/s41592-024-02233-6": {"key": "ABC123", "doi": "..."}}

Raw lines 83 to 90

91## Output Format

93By default the CLI outputs human-readable text including title, authors, date, publication, volume, issue, DOI, URL, and PDF attachment paths.

95Use `--json` for structured JSON output suitable for piping to other tools.

Output Format

By default the CLI outputs human-readable text including title, authors, date, publication, volume, issue, DOI, URL, and PDF attachment paths.

Use --json for structured JSON output suitable for piping to other tools.

Raw lines 91 to 96

97## Search Behaviour Notes

99- Default search covers top-level item titles and metadata fields only

100- `--fulltext` expands search to PDF content; results show parent bibliographic items (not raw attachments)

101- Multiple `--tag` flags use AND logic

102- Multiple `--itemtype` flags use OR logic

103

Search Behaviour Notes

Default search covers top-level item titles and metadata fields only
--fulltext expands search to PDF content; results show parent bibliographic items (not raw attachments)
Multiple --tag flags use AND logic
Multiple --itemtype flags use OR logic

Raw lines 97 to 103

104## Authorized Local Writes (Zotero 10+)

105

106The CLI also supports local writes in the reviewed 1.15.2 release. These are illustrative commands, not part of the read-only smoke test:

107

108```bash

109# Zotero displays its authorization dialog; choose the scope you intend.

110pyzotero authorize --app-name "Research library tool"

111pyzotero listitemfields journalArticle

112pyzotero createitem items.json --json

113pyzotero createcollection "Review papers" --json

114pyzotero addtocollection COLKEY ITEMKEY --json

115pyzotero removefromcollection COLKEY ITEMKEY --json

116pyzotero movetocollection --from OLDCOLKEY --to NEWCOLKEY ITEMKEY --json

117```

118

119`items.json` contains an editable item object or array of objects. Validate bibliographic metadata before importing. The stored persistent local key and server ID are in `$XDG_CONFIG_HOME/pyzotero/local-api-key.json` (default `~/.config/pyzotero/local-api-key.json`); a Web API key does not authorize these commands. Collection membership commands update one item at a time.

120

121For Semantic Scholar CLI commands (`related`, `citations`, `references`, `s2search`), network access is required; see the limitations in [mcp.md](mcp.md). Sources: [CLI documentation](https://pyzotero.readthedocs.io/en/latest/#command-line-interface), [release CLI source](https://github.com/urschrei/pyzotero/blob/v1.15.2/src/pyzotero/cli.py).

Authorized Local Writes (Zotero 10+)

The CLI also supports local writes in the reviewed 1.15.2 release. These are illustrative commands, not part of the read-only smoke test:

# Zotero displays its authorization dialog; choose the scope you intend.
pyzotero authorize --app-name "Research library tool"
pyzotero listitemfields journalArticle
pyzotero createitem items.json --json
pyzotero createcollection "Review papers" --json
pyzotero addtocollection COLKEY ITEMKEY --json
pyzotero removefromcollection COLKEY ITEMKEY --json
pyzotero movetocollection --from OLDCOLKEY --to NEWCOLKEY ITEMKEY --json

items.json contains an editable item object or array of objects. Validate bibliographic metadata before importing. The stored persistent local key and server ID are in $XDG_CONFIG_HOME/pyzotero/local-api-key.json (default ~/.config/pyzotero/local-api-key.json); a Web API key does not authorize these commands. Collection membership commands update one item at a time.

For Semantic Scholar CLI commands (related, citations, references, s2search), network access is required; see the limitations in mcp.md. Sources: CLI documentation, release CLI source.

Raw lines 104 to 121