Skills › Scientific Agent Skills › paperzilla › cli-contracts.md

cli-contracts.md

102 lines · skills/paperzilla/references/cli-contracts.md at 5f2bc03

Uses an outside tool

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Paperzilla CLI contracts

3Reviewed 2026-10-01 against `pz` **v0.7.1**, commit

4`798a8c12c8aa8e18a8fbede4a2bfaaea2950ea5c`. These are the routes used by that

5release, not a promise of a stable public REST SDK. Prefer the CLI for this skill;

6the public API reference documents feed and MCP integration surfaces.

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.

Raw lines 1 to 7

Uses an outside tool MCP :6

8## Authentication and transport

10`pz login` sends `POST /api/auth/otp` with JSON `email`, then

11`POST /api/auth/verify` with `email` and `code`. Verification returns

12`access_token`, `refresh_token`, and `expires_in`. Refresh uses

13`POST /api/auth/refresh` with both existing tokens in the JSON body. Those three

14requests do not use a bearer header. The session is stored in

15`~/.paperzilla/tokens.json` unless `PZ_TOKENS_PATH` is set.

17All data commands in v0.7.1 first load a session and call

18`GET /api/auth/cli-access` with `Authorization: Bearer ...`; success requires

19`allowed: true`. Commands also send `X-Paperzilla-Client: cli` and a versioned

20`User-Agent`. Project, recommendation, feedback, and feed-token requests use

21bearer authentication. Canonical public-paper requests omit the bearer header

22**after** this authenticated preflight. The current guide's claim that

23`pz paper` works without login conflicts with both this release's source and

24local binary behavior. Treat login as required for the reviewed CLI.

26The default base URL is `https://paperzilla.ai`. `PZ_API_URL` replaces it; do not

27send account tokens to an arbitrary replacement host. Missing/expired sessions

28can cause interactive login and contaminate stdout, including `--json` exports.

29`CLI_UPGRADE_REQUIRED` and `CLI_ENTITLEMENT_UNAVAILABLE` describe access failures,

30not zero search results. The CLI can retry a request after a 401 and token

31refresh; other service failures are returned to the caller.

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.

Raw lines 8 to 32

33## Command-to-request mapping

35Paths are relative to the configured base URL. Braced identifiers come from

36returned records, never inferred from DOI or title.

38| CLI operation | Request | Result or side effect |

39| --- | --- | --- |

40| `project list` | `GET /api/projects` | API project array; CLI `--json` emits only `id`, `name`, `mode`, `visibility`. No pagination flags in this release. |

41| `project {project}` | `GET /api/projects/{project}` | Project record, including keyword/source/category arrays. |

42| `feed {project}` | `GET /api/projects/{project}/feed` | `items`, `total`, `limit`, `offset`; query keys `must_read`, `since`, `limit`, `offset`. |

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

44| `paper {paper}` | `GET /api/public/papers/{paper}` | Canonical paper object. |

45| `paper {paper} --markdown` | `GET /api/public/papers/{paper}/markdown` | Markdown text when available; `markdown_not_ready` means nothing was queued through this public route. |

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

47| `rec {recommendation}` | `GET /api/project-papers/{recommendation}` | Recommendation object containing canonical `paper`. |

48| `rec {recommendation} --markdown` | `GET /api/project-papers/{recommendation}/markdown` | Text or a pending-generation response; this GET can queue generation. |

49| `feedback {recommendation} {vote}` | `PUT /api/project-papers/{recommendation}/feedback` | JSON body `vote` and optional `downvote_reason`; returns `vote`, `downvote_reason`, `updated_at`. |

50| `feedback clear {recommendation}` | `DELETE /api/project-papers/{recommendation}/feedback` | Backend 204; CLI `--json` supplies a `project_paper_ref`/`cleared` envelope. |

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

53For compatibility, canonical-paper 404s may cause v0.7.1 to try authenticated

54`GET /api/papers/{ref}` or `/api/papers/{ref}/markdown`. A successful fallback

55prints a deprecation warning for a recommendation ID. Do not build a new workflow

56around these legacy routes; use `rec` with the returned recommendation ID.

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.

Raw lines 33 to 57

58## Pagination, identifiers, and output

60- Browse accepts zero-based `offset`; positive `limit` is sent to the API, with

61 no verified server maximum in the inspected CLI source. Use a modest page size

62 and honor the returned values. `since` means recommendation readiness time.

63- Search validates explicit `limit` in 1–100, nonnegative `offset`, and trimmed

64 query length in 3–200. The Go implementation counts UTF-8 bytes, so multibyte

65 queries may reach its limit before 200 visible characters. `has_more`, not a

66 total or the text display's count, determines whether more results exist.

67- Neither command automatically consumes all pages. Keep a finite page/request

68 budget and stop on an empty/nonadvancing page; record a partial export if the

69 budget is reached. A changing feed can shift offset-based pages.

70- Recommendation `id`/`short_id` differ from nested canonical

71 `paper.id`/`paper.short_id`. `paper --project --json` returns a recommendation,

72 unlike canonical `paper --json`.

73- `--markdown` is mutually exclusive with `--json` for `paper` and `rec`.

74 `markdown_queued`/`markdown_already_queued` are rendered as friendly messages

75 with successful exit status. Exit code zero alone does not prove full-text

76 retrieval. Do not derive scientific claims from those status messages.

77- The API documents nullable `pdf_url`; the CLI decodes string fields into Go

78 strings, so a missing/null URL can appear as an empty string in CLI JSON.

79- Atom output contains a credential, not an ordinary public paper link. Browse

80 flags do not constrain this URL. Obtain it only for the requested feed-reader

81 workflow, and do not publish it with citations.

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.

Raw lines 58 to 82

83## Verification and sources

85The official darwin-arm64 v0.7.1 binary was downloaded and checked against its

86release SHA-256 list. Version/help and 25 local mock-server cases exercised

87project, browse/search, canonical/project-paper, markdown-ready/pending,

88feedback/clear, Atom construction, input validation, OTP, refresh, and the

89canonical auth preflight. The mock server held only synthetic data and tokens.

90No live account login, email, generation job, feedback, or feed-token creation

91was performed. Live service authorization, entitlements, and returned scientific

92records remain untested. Install/build/update instructions were checked against

93official documentation; only the release binary was executed.

95- [CLI guide](https://docs.paperzilla.ai/guides/cli)

96- [Quickstart](https://docs.paperzilla.ai/guides/cli-getting-started)

97- [Public integration scope](https://docs.paperzilla.ai/api-reference/introduction)

98- [Atom route and credential semantics](https://docs.paperzilla.ai/api-reference/rss-atom-feed)

99- [v0.7.1 release](https://github.com/paperzilla-ai/pz/releases/tag/v0.7.1)

100- [CLI command source](https://github.com/paperzilla-ai/pz/tree/v0.7.1/cmd)

101- [HTTP client, auth, endpoints and schemas](https://github.com/paperzilla-ai/pz/tree/v0.7.1/internal/api)

102- [Session storage](https://github.com/paperzilla-ai/pz/blob/v0.7.1/internal/config/tokens.go)

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.

Raw lines 83 to 102