CLI

The Paperzilla CLI (pz) lets you read canonical papers by Paperzilla paper ID, browse or search your curated project feeds, inspect project-specific recommendations, and leave feedback from the terminal. It works for both humans and AI agents. Use --json when you want structured output. The main exceptions are login and update. If you just installed pz and want the shortest path to a working setup, start with CLI getting started.

Install

macOS
Windows
Linux
From source

brew install paperzilla-ai/tap/pz

Homebrew 6.0 and later requires explicit trust for non-official taps. If Homebrew reports Refusing to load formula paperzilla-ai/tap/pz from untrusted tap paperzilla-ai/tap, trust only the Paperzilla formula and retry:

brew trust --formula paperzilla-ai/tap/pz
brew install paperzilla-ai/tap/pz

See Homebrew’s tap trust documentation. Do not disable tap trust globally.

Via Scoop:

scoop bucket add paperzilla-ai https://github.com/paperzilla-ai/scoop-bucket
scoop install pz

Download from GitHub Releases:

curl -sL https://github.com/paperzilla-ai/pz/releases/latest/download/pz_linux_amd64.tar.gz | tar xz
sudo mv pz /usr/local/bin/

Requires Go 1.23+:

git clone https://github.com/paperzilla-ai/pz.git
cd pz
go build -o pz .
mv pz /usr/local/bin/

Update

Run:

pz update

pz update checks whether your current CLI is on the latest release and then prints upgrade instructions for how you installed it.

Homebrew installs show brew update and brew upgrade pz
Scoop installs show scoop update pz
GitHub release installs tell you which release artifact to download
Source builds tell you to git pull and rebuild

On Homebrew 6.0 and later, an existing installation may need explicit trust before it can update. If brew update refuses to load the Paperzilla formula from an untrusted tap, run:

brew trust --formula paperzilla-ai/tap/pz
brew update
brew upgrade pz

Trusting only the formula follows Homebrew’s recommended narrower scope. Do not disable tap trust globally. pz update auto-detects common install methods from the current executable and build metadata. If detection is ambiguous, override it explicitly:

pz update --install-method homebrew
pz update --install-method scoop
pz update --install-method release
pz update --install-method source

Supported values are auto, homebrew, scoop, release, and source. To check the currently installed version:

pz --version

Log in

Authenticate with your Paperzilla account. You receive a one-time code via email.

Don’t have an account yet? Follow the quickstart to sign up first.

pz login

Email: you@example.com
Sending magic link...
Check your email, enter the code: 123456
Logged in!

You need to sign in for project-oriented commands such as project, feed, feed search, rec, and feedback, and to request markdown generation for project recommendations. If you only want to open a canonical paper by internal Paperzilla paper ID, pz paper <paper-ref> also works without logging in.

Commands

pz update

Check whether your CLI is current and print install-specific upgrade steps.

pz update

If you use a source build or the install method was guessed incorrectly, override detection:

pz update --install-method source

pz project list

List all your projects.

pz project list

ID                                    NAME                       MODE        VISIBILITY  CREATED
a1b2c3d4-e5f6-7890-abcd-ef1234567890  Machine Learning Papers    auto        private     2025-06-15 10:30
b2c3d4e5-f6a7-8901-bcde-f12345678901  Genomics Research          auto        private     2025-07-20 14:15

Use the ID column for project-scoped commands such as pz feed, pz feed search, and pz paper --project. Add --json when you want structured output for scripting or AI agents. pz project list --json returns a compact summary array with the same project identity fields shown in the table: id, name, mode, and visibility.

pz project <id>

Show details for a specific project.

pz project a1b2c3d4-e5f6-7890-abcd-ef1234567890

Name:             Machine Learning Papers
ID:               a1b2c3d4-e5f6-7890-abcd-ef1234567890
Mode:             auto
Visibility:       private
Matching State:   active
Email Frequency:  daily
Email Time:       09:00
Max Candidates:   100
Max Papers/Digest:20
Created:          2025-06-15 10:30
Activated:        2025-06-16 00:00
Last Digest:      2025-08-01 09:00

Interest:
  Recent advances in transformer architectures and efficiency

Add --json to return the full project record:

pz project a1b2c3d4-e5f6-7890-abcd-ef1234567890 --json

The JSON record includes project definition metadata: positive_keywords, negative_keywords, watched sources, and watched categories.

pz paper <paper-ref>

Show details for a canonical Paperzilla paper. paper-ref may be:

a full paper UUID
a paper short_id

This command works without logging in. When you add --project <project-id>, pz paper resolves that canonical paper inside one of your projects and shows recommendation context. That mode requires login.

pz paper 33403e66-bfc3-43e7-a849-14b03341201e

Title:           A Novel Approach to Transformer Efficiency
ID:              33403e66-bfc3-43e7-a849-14b03341201e
Short ID:        abc12345
Slug:            a-novel-approach
Source:          arxiv
Published:       2025-07-20
Authors:         Jane Smith, John Chen
URL:             https://example.org/paper
PDF URL:         https://example.org/paper.pdf
DOI:             10.1234/example
Source Paper ID: 2507.12345

Flags

Flag	Short	Description
`--json`	`-j`	Output the full paper as JSON
`--markdown`		Print raw paper markdown to stdout when it is already available
`--project`		Resolve this paper inside one of your projects and show recommendation context

Examples

# Inspect a canonical paper by UUID or short ID
pz paper <paper-id>

# Show the same paper as it appears in one of your projects
pz paper <paper-id> --project <project-id>

# Print raw markdown when it is already prepared
pz paper <paper-id> --markdown

If markdown is not ready yet, the CLI prints a friendly message. Anonymous pz paper --markdown does not queue markdown generation. For project-scoped agent workflows, pz rec <project-paper-id> --markdown is often a better follow-up after pz feed or pz feed search, because the recommendation context can queue markdown generation. If you are new to the model, see What is the difference between a canonical paper and a recommendation?.

pz rec <project-paper-ref>

Show details for one recommendation from one of your projects. project-paper-ref may be:

a full project_paper UUID returned by pz feed --json
a project_paper short_id returned by pz feed --json

This command requires login.

pz rec bb31f558

Title:             A Novel Approach to Transformer Efficiency
Recommendation ID: bb31f558-9613-4552-990a-30fb3ac48602
Short ID:          bb31f558
Relevance:         Must Read (92%)
Feedback:          star
Ready At:          2025-08-01 09:00

Summary:
  This paper is highly relevant because it introduces...

Paper:
  ID:              33403e66-bfc3-43e7-a849-14b03341201e
  Short ID:        abc12345
  Source:          arxiv
  Published:       2025-07-20

Flags

Flag	Short	Description
`--json`	`-j`	Output the recommendation as JSON
`--markdown`		Print raw paper markdown to stdout, queueing generation if needed

Examples

# Open a recommendation using the ID returned by the feed
pz rec <project-paper-id>

# Fetch the first recommendation from a project feed
pz feed <project-id> --json | jq -r '.items[0].id' | xargs pz rec

# Print markdown for the recommended paper
pz rec <project-paper-id> --markdown

If markdown is still being prepared, the CLI prints a one-line message and asks you to try again in a minute or so.

pz feedback <project-paper-ref> <upvote|downvote|star>

Leave a recommendation signal for one paper in one project. Supported feedback values:

upvote
downvote
star

Flags

Flag	Short	Description
`--json`	`-j`	Output the feedback object as JSON
`--reason`		Optional downvote reason: `not_relevant` or `low_quality`

Examples

# Positive signal
pz feedback <project-paper-id> upvote

# Positive signal as JSON
pz feedback <project-paper-id> upvote --json

# Strong positive signal
pz feedback <project-paper-id> star

# Negative signal with an explicit reason
pz feedback <project-paper-id> downvote --reason not_relevant

# Clear any existing feedback
pz feedback clear <project-paper-id>

# Clear feedback and get a confirmation envelope
pz feedback clear <project-paper-id> --json

Feedback is project-specific. The same canonical paper can have different feedback in different projects. To remove feedback entirely, use pz feedback clear <project-paper-ref>. clear is a subcommand. Use pz feedback clear <project-paper-ref>, not pz feedback <project-paper-ref> clear. For a shorter explanation, see How do feedback signals work in the CLI?.

pz feed <project-id>

Browse the curated paper feed for a project.

pz feed a1b2c3d4-e5f6-7890-abcd-ef1234567890

Machine Learning Papers — 12 papers (total: 142)

★ Must Read  A Novel Approach to Transformer Efficiency
  Smith et al. · arxiv · 2025-08-01 · relevance: 92%

○ Related  On the Convergence Properties of Diffusion Models
  Chen et al. · arxiv · 2025-07-30 · relevance: 74%

Each paper shows a relevance class (★ Must Read or ○ Related), title, first author, source, date, and relevance score. Use recommendation IDs from the feed with pz rec, and canonical paper IDs with pz paper.

Flags

Flag	Short	Description
`--json`	`-j`	Output as JSON
`--must-read`	`-m`	Only show must-read papers
`--since`	`-s`	Only papers after this date (ISO 8601 or `YYYY-MM-DD`)
`--limit`	`-n`	Limit number of results
`--atom`		Print Atom feed URL for feed readers

Examples

# Only must-read papers from the last week
pz feed <project-id> --must-read --since 2025-07-25 --limit 5

# Export as JSON for scripting
pz feed <project-id> --json

# Pipe to jq
pz feed <project-id> --json | jq '.items[].paper.title'

# Get Atom feed URL for your feed reader
pz feed <project-id> --atom

pz feed search

Search across the full feed for one project. Use pz project list first if you need to look up the project ID.

pz project list

pz feed search --project-id a1b2c3d4-e5f6-7890-abcd-ef1234567890 --query "latent retrieval"

Machine Learning Papers — 2 papers
Query: latent retrieval
Has more: true

★ Must Read [★]  Latent Retrieval for Papers
  Smith et al. · arXiv · 2026-04-01 · relevance: 95%

○ Related  Prefix Matching in Search
  Chen · ICLR · 2026-03-30 · relevance: 76%

This command searches the whole project feed, not just already loaded browse pages. Search is rank-first. It does not return an exact total count in v1. Query terms use prefix matching, so Proxi matches Proximity.

Flags

Flag	Short	Description
`--project-id`		Project ID to search
`--query`	`-q`	Search query, 3 to 200 characters after trim
`--feedback-filter`		Filter by `all`, `unrated`, `liked`, `disliked`, `starred`, `not-relevant`, or `low-quality`
`--must-read`	`-m`	Only return Must Read papers
`--limit`	`-n`	Limit results per page, up to 100
`--offset`		Skip results for pagination
`--json`	`-j`	Output the search envelope as JSON

Examples

# Find your project ID first
pz project list

# Search one project feed
pz feed search --project-id <project-id> --query "latent retrieval"

# Use prefix search
pz feed search --project-id <project-id> --query "Proxi"

# Search only starred papers
pz feed search --project-id <project-id> --query "retrieval" --feedback-filter starred

# Search only Must Read papers
pz feed search --project-id <project-id> --query "retrieval" --must-read

# Get JSON for scripting
pz feed search --project-id <project-id> --query "latent retrieval" --json

# Fetch the next page only if the previous response had has_more = true
pz feed search --project-id <project-id> --query "latent retrieval" --limit 20 --offset 20

The JSON response includes:

items
limit
offset
has_more
query

If you want a shorter answer, see How do I search a project feed from the CLI? and How do I find my project ID for CLI commands?.

Atom feeds

The --atom flag prints a URL you can paste into any feed reader (Vienna RSS, NetNewsWire, Feedly, etc.):

pz feed <project-id> --atom

https://paperzilla.ai/api/feed/atom/a1b2c3d4-...?token=pzft_...

The URL contains a personal feed token so the reader can poll without logging in. The token is per-user, and the same URL is returned on repeated calls. See the feeds guide for more on RSS/Atom.

JSON output

With --json, pz feed returns structured data suitable for scripting and AI agents:

{
  "items": [
    {
      "id": "bb31f558-9613-4552-990a-30fb3ac48602",
      "short_id": "bb31f558",
      "paper_title": "A Novel Approach to...",
      "relevance_score": 0.92,
      "relevance_class": 2,
      "personalized_note": "Relevant because...",
      "ready_at": "2025-08-01T09:00:00Z",
      "feedback": {
        "vote": "star",
        "downvote_reason": null,
        "updated_at": "2025-08-01T09:10:00Z"
      },
      "paper": {
        "id": "33403e66-bfc3-43e7-a849-14b03341201e",
        "short_id": "abc12345",
        "title": "A Novel Approach to...",
        "authors": [{"name": "Jane Smith"}],
        "published_date": "2025-07-20",
        "reference_label": "PMID 45678901",
        "doi": "10.1000/example.2026.12345",
        "pdf_url": null,
        "url": "https://pubmed.ncbi.nlm.nih.gov/45678901/",
        "source_id": 5,
        "source_paper_id": "45678901",
        "source": {
          "name": "pubmed"
        }
      }
    }
  ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Relevance classes: 2 = Must Read, 1 = Related Recommendation IDs: use items[].id or items[].short_id with pz rec and pz feedback Paper IDs: use items[].paper.id or items[].paper.short_id with pz paper Source IDs: 1 = arXiv, 2 = medRxiv, 3 = bioRxiv, 4 = ChinaXiv, 5 = PubMed, 6 = ChemRxiv For PubMed records, reference_label uses the PMID even when doi is present. pdf_url is nullable for every source. Use url for the source landing page when no PDF is available. pz project list --json returns project summary objects with id, name, mode, and visibility. pz project <project-id> --json returns the full project record, including project definition metadata: positive_keywords, negative_keywords, watched sources, and watched categories. pz feedback <project-paper-id> ... --json returns the feedback object. pz feedback clear <project-paper-id> --json returns a small confirmation envelope because the backend clear endpoint returns 204 No Content. pz feed search --json returns a search envelope with items, limit, offset, has_more, and query.

OpenClaw skill

The Paperzilla CLI is also available as an OpenClaw skill on ClawHub. This lets AI agents like OpenClaw, Claude Code, Cursor, and Windsurf use pz commands directly. For the full setup flow, see Use the Paperzilla CLI with OpenClaw. If you already use OpenClaw, install the skill with:

openclaw skills install paperzilla

If you already use the separate ClawHub CLI, this also works:

clawhub install paperzilla

Once installed, your agent can list projects, inspect papers, browse or search feeds, and filter papers without manual CLI invocation. The skill wraps the same pz commands documented above.

You still need the pz binary installed and authenticated. The skill teaches the agent how to use it — it does not replace the CLI itself.

Configuration

Variable	Description	Default
`PZ_API_URL`	API base URL	`https://paperzilla.ai`

What is Paperzilla

Getting started

Core guides

Q&A

Install

Update

Log in

Commands

pz update

pz project list

pz project <id>

pz paper <paper-ref>

Flags

Examples

pz rec <project-paper-ref>

Flags

Examples

pz feedback <project-paper-ref> <upvote|downvote|star>

Flags

Examples

pz feed <project-id>

Flags

Examples

pz feed search

Flags

Examples

Atom feeds

JSON output

OpenClaw skill

Configuration

​Install

​Update

​Log in

​Commands

​pz update

​pz project list

​pz project <id>

​pz paper <paper-ref>

​Flags

​Examples

​pz rec <project-paper-ref>

​Flags

​Examples

​pz feedback <project-paper-ref> <upvote|downvote|star>

​Flags

​Examples

​pz feed <project-id>

​Flags

​Examples

​pz feed search

​Flags

​Examples

​Atom feeds

​JSON output

​OpenClaw skill

​Configuration

Install

Update

Log in

Commands

pz update

pz project list

pz project <id>

pz paper <paper-ref>

Flags

Examples

pz rec <project-paper-ref>

Flags

Examples

pz feedback <project-paper-ref> <upvote|downvote|star>

Flags

Examples

pz feed <project-id>

Flags

Examples

pz feed search

Flags

Examples

Atom feeds

JSON output

OpenClaw skill

Configuration