CLI

The Paperzilla CLI (pz) lets you read canonical papers by Paperzilla paper ID, browse 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. 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

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

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, 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

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

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. 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
`--reason`		Optional downvote reason: `not_relevant` or `low_quality`

Examples

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

# 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>

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

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, the 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",
        "pdf_url": "https://arxiv.org/pdf/2507.12345",
        "url": "https://arxiv.org/abs/2507.12345",
        "source_id": 1,
        "source": {
          "name": "arxiv"
        }
      }
    }
  ],
  "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, 6 = ChemRxiv

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

Atom feeds

JSON output

OpenClaw skill

Configuration

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

​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

Atom feeds

JSON output

OpenClaw skill

Configuration