> ## Documentation Index > Fetch the complete documentation index at: https://docs.paperzilla.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Use the Paperzilla CLI to read papers, search project feeds, inspect recommendations, and manage projects from your terminal export const AiAgents = ({path}) => AI agents: This page is available as markdown. See also the docs index and full docs. ; 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](/guides/cli-getting-started). ## Install ```bash theme={null} 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: ```bash theme={null} brew trust --formula paperzilla-ai/tap/pz brew install paperzilla-ai/tap/pz ``` See [Homebrew's tap trust documentation](https://docs.brew.sh/Tap-Trust). Do not disable tap trust globally. Via [Scoop](https://scoop.sh): ```bash theme={null} scoop bucket add paperzilla-ai https://github.com/paperzilla-ai/scoop-bucket scoop install pz ``` Download from [GitHub Releases](https://github.com/paperzilla-ai/pz/releases): ```bash theme={null} 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+: ```bash theme={null} git clone https://github.com/paperzilla-ai/pz.git cd pz go build -o pz . mv pz /usr/local/bin/ ``` ## Update Run: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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](/quickstart) to sign up first. ```bash theme={null} 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 ` also works without logging in. ## Commands ### pz update Check whether your CLI is current and print install-specific upgrade steps. ```bash theme={null} pz update ``` If you use a source build or the install method was guessed incorrectly, override detection: ```bash theme={null} pz update --install-method source ``` ### pz project list List all your projects. ```bash theme={null} 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 \ Show details for a specific project. ```bash theme={null} 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: ```bash theme={null} 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 \ 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 `, `pz paper` resolves that canonical paper inside one of your projects and shows recommendation context. That mode requires login. ```bash theme={null} 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 ```bash theme={null} # Inspect a canonical paper by UUID or short ID pz paper # Show the same paper as it appears in one of your projects pz paper --project # Print raw markdown when it is already prepared pz paper --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 --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?](/answers/what-is-the-difference-between-a-canonical-paper-and-a-recommendation). ### pz rec \ 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. ```bash theme={null} 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 ```bash theme={null} # Open a recommendation using the ID returned by the feed pz rec # Fetch the first recommendation from a project feed pz feed --json | jq -r '.items[0].id' | xargs pz rec # Print markdown for the recommended paper pz rec --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 \ \ 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 ```bash theme={null} # Positive signal pz feedback upvote # Positive signal as JSON pz feedback upvote --json # Strong positive signal pz feedback star # Negative signal with an explicit reason pz feedback downvote --reason not_relevant # Clear any existing feedback pz feedback clear # Clear feedback and get a confirmation envelope pz feedback clear --json ``` Feedback is project-specific. The same canonical paper can have different feedback in different projects. To remove feedback entirely, use `pz feedback clear `. `clear` is a subcommand. Use `pz feedback clear `, not `pz feedback clear`. For a shorter explanation, see [How do feedback signals work in the CLI?](/answers/how-do-feedback-signals-work-in-the-cli). ### pz feed \ Browse the curated paper feed for a project. ```bash theme={null} 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 ```bash theme={null} # Only must-read papers from the last week pz feed --must-read --since 2025-07-25 --limit 5 # Export as JSON for scripting pz feed --json # Pipe to jq pz feed --json | jq '.items[].paper.title' # Get Atom feed URL for your feed reader pz feed --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. ```bash theme={null} pz project list ``` ```bash theme={null} 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 ```bash theme={null} # Find your project ID first pz project list # Search one project feed pz feed search --project-id --query "latent retrieval" # Use prefix search pz feed search --project-id --query "Proxi" # Search only starred papers pz feed search --project-id --query "retrieval" --feedback-filter starred # Search only Must Read papers pz feed search --project-id --query "retrieval" --must-read # Get JSON for scripting pz feed search --project-id --query "latent retrieval" --json # Fetch the next page only if the previous response had has_more = true pz feed search --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?](/answers/how-do-i-search-a-project-feed-from-the-cli) and [How do I find my project ID for CLI commands?](/answers/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.): ```bash theme={null} pz feed --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](/guides/feeds) for more on RSS/Atom. ## JSON output With `--json`, `pz feed` returns structured data suitable for scripting and AI agents: ```json theme={null} { "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 --json` returns the full project record, including project definition metadata: `positive_keywords`, `negative_keywords`, watched `sources`, and watched `categories`. `pz feedback ... --json` returns the feedback object. `pz feedback clear --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](https://clawhub.ai/pors/paperzilla). 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](/guides/openclaw). If you already use OpenClaw, install the skill with: ```bash theme={null} openclaw skills install paperzilla ``` If you already use the separate ClawHub CLI, this also works: ```bash theme={null} 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` |