AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

paperzilla

Reads projects, searches project feeds, and retrieves recommendations and canonical papers in Paperzilla through the pz CLI. Supports recent recommendations, paper details, markdown-based summaries, recommendation feedback, JSON export, and Atom feed URLs.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--paperzilla at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 2

references/cli-contracts.md

Paperzilla CLI contracts

Reviewed 2026-10-01 against pz v0.7.1, commit 798a8c12c8aa8e18a8fbede4a2bfaaea2950ea5c. These are the routes used by that release, not a promise of a stable public REST SDK. Prefer the CLI for this skill; the public API reference documents feed and MCP integration surfaces.

Authentication and transport

pz login sends POST /api/auth/otp with JSON email, then POST /api/auth/verify with email and code. Verification returns access_token, refresh_token, and expires_in. Refresh uses POST /api/auth/refresh with both existing tokens in the JSON body. Those three requests do not use a bearer header. The session is stored in ~/.paperzilla/tokens.json unless PZ_TOKENS_PATH is set.

All data commands in v0.7.1 first load a session and call GET /api/auth/cli-access with Authorization: Bearer ...; success requires allowed: true. Commands also send X-Paperzilla-Client: cli and a versioned User-Agent. Project, recommendation, feedback, and feed-token requests use bearer authentication. Canonical public-paper requests omit the bearer header after this authenticated preflight. The current guide's claim that pz paper works without login conflicts with both this release's source and local binary behavior. Treat login as required for the reviewed CLI.

The default base URL is https://paperzilla.ai. PZ_API_URL replaces it; do not send account tokens to an arbitrary replacement host. Missing/expired sessions can cause interactive login and contaminate stdout, including --json exports. CLI_UPGRADE_REQUIRED and CLI_ENTITLEMENT_UNAVAILABLE describe access failures, not zero search results. The CLI can retry a request after a 401 and token refresh; other service failures are returned to the caller.

Command-to-request mapping

Paths are relative to the configured base URL. Braced identifiers come from returned records, never inferred from DOI or title.

| CLI operation | Request | Result or side effect | | --- | --- | --- | | project list | GET /api/projects | API project array; CLI --json emits only id, name, mode, visibility. No pagination flags in this release. | | project {project} | GET /api/projects/{project} | Project record, including keyword/source/category arrays. | | feed {project} | GET /api/projects/{project}/feed | items, total, limit, offset; query keys must_read, since, limit, offset. | | feed search --project-id {project} | GET /api/projects/{project}/feed/search | Query q, feedback_filter, optional must_read, limit, offset; response items, limit, offset, has_more, query. | | paper {paper} | GET /api/public/papers/{paper} | Canonical paper object. | | paper {paper} --markdown | GET /api/public/papers/{paper}/markdown | Markdown text when available; markdown_not_ready means nothing was queued through this public route. | | paper {paper} --project {project} | GET /api/projects/{project}/papers/{paper} | Project recommendation object containing its canonical paper. With --markdown, subsequently uses the recommendation markdown route. | | rec {recommendation} | GET /api/project-papers/{recommendation} | Recommendation object containing canonical paper. | | rec {recommendation} --markdown | GET /api/project-papers/{recommendation}/markdown | Text or a pending-generation response; this GET can queue generation. | | feedback {recommendation} {vote} | PUT /api/project-papers/{recommendation}/feedback | JSON body vote and optional downvote_reason; returns vote, downvote_reason, updated_at. | | feedback clear {recommendation} | DELETE /api/project-papers/{recommendation}/feedback | Backend 204; CLI --json supplies a project_paper_ref/cleared envelope. | | feed {project} --atom | POST /api/auth/feed-token | Gets or creates a personal token; CLI constructs /api/feed/atom/{project}?token=..., without fetching its XML. |

For compatibility, canonical-paper 404s may cause v0.7.1 to try authenticated GET /api/papers/{ref} or /api/papers/{ref}/markdown. A successful fallback prints a deprecation warning for a recommendation ID. Do not build a new workflow around these legacy routes; use rec with the returned recommendation ID.

Pagination, identifiers, and output

  • Browse accepts zero-based offset; positive limit is sent to the API, with no verified server maximum in the inspected CLI source. Use a modest page size and honor the returned values. since means recommendation readiness time.
  • Search validates explicit limit in 1–100, nonnegative offset, and trimmed query length in 3–200. The Go implementation counts UTF-8 bytes, so multibyte queries may reach its limit before 200 visible characters. has_more, not a total or the text display's count, determines whether more results exist.
  • Neither command automatically consumes all pages. Keep a finite page/request budget and stop on an empty/nonadvancing page; record a partial export if the budget is reached. A changing feed can shift offset-based pages.
  • Recommendation id/short_id differ from nested canonical paper.id/paper.short_id. paper --project --json returns a recommendation, unlike canonical paper --json.
  • --markdown is mutually exclusive with --json for paper and rec. markdown_queued/markdown_already_queued are rendered as friendly messages with successful exit status. Exit code zero alone does not prove full-text retrieval. Do not derive scientific claims from those status messages.
  • The API documents nullable pdf_url; the CLI decodes string fields into Go strings, so a missing/null URL can appear as an empty string in CLI JSON.
  • Atom output contains a credential, not an ordinary public paper link. Browse flags do not constrain this URL. Obtain it only for the requested feed-reader workflow, and do not publish it with citations.

Verification and sources

The official darwin-arm64 v0.7.1 binary was downloaded and checked against its release SHA-256 list. Version/help and 25 local mock-server cases exercised project, browse/search, canonical/project-paper, markdown-ready/pending, feedback/clear, Atom construction, input validation, OTP, refresh, and the canonical auth preflight. The mock server held only synthetic data and tokens. No live account login, email, generation job, feedback, or feed-token creation was performed. Live service authorization, entitlements, and returned scientific records remain untested. Install/build/update instructions were checked against official documentation; only the release binary was executed.