Work from your computer

Install the client

The CLI is Peerpedia’s command-line client. You need Python 3.12 or newer. You do not need Git or the website’s server software.

If you have pipx, install the released client from PyPI with one command.

pipx install peerpedia-cli
peerpedia --version

The version should read peerpedia 0.1.1. You can also download the wheel from the GitHub release and give its file path to pipx install.

python3 -m venv ~/.venvs/peerpedia
source ~/.venvs/peerpedia/bin/activate

py -m venv "$env:USERPROFILE\.venvs\peerpedia"
& "$env:USERPROFILE\.venvs\peerpedia\Scripts\Activate.ps1"

python -m pip install peerpedia-cli
peerpedia --help

Find and download a paper

Reading does not require an account or a token. Search for a title, author, or topic.

peerpedia search "Galois" --server https://peerpedia.dev

Each result includes a permanent paper number, such as 261025.a7c92e4b10d3, and its internal UUID. You can also find it in the paper’s details-page address, between /papers/ and the final slash. In the next command, replace PAPER_ID with that value. The client also accepts the paper’s details-page URL.

peerpedia clone PAPER_ID my-paper --server https://peerpedia.dev
cd my-paper

You can also replace PAPER_ID with a snapshot’s reading URL. This downloads that exact version, even if the paper has since changed.

Clone downloads a local working copy. For a single-page paper, paper.md holds the text and paper.json holds the title, authors, abstract, subjects, and license. For a work with chapters, the JSON file lists its Markdown files.

Keep the hidden .peerpedia directory with your working copy. It records which paper and accepted version you started from. Do not edit its contents by hand.

Run the remaining commands from inside this working-copy folder unless a step says otherwise.

Connect your account

To submit changes, the CLI needs an access token, a credential that gives it limited permission to act through your account.

1. Sign in on the website, verify your email, and accept the submission agreement.
2. Open Access tokens, confirm your password, and create a token. Enable Also allow publishing new papers if you want to create new work, rather than only propose edits.
3. Run the command below. Paste the token at the hidden prompt, not into the command itself.

peerpedia login https://peerpedia.dev

If you signed up through Google and have no Peerpedia password, open Account and choose Add a password by email first.

Keep tokens out of Markdown files, messages, and Git repositories. You can revoke one on the Access tokens page. A token cannot accept PRs, post comments, give ratings, vote, or grant administrator access.

Submit an edit

A PR is a proposed change that the corresponding author reviews before accepting. Edit your local Markdown file, then inspect the difference from the version you downloaded.

peerpedia diff

When the change is ready, push submits it. The message explains what you changed and why.

peerpedia push -m "State the compactness assumption before the proof"
peerpedia status

This creates a public PR and prints its address. It does not replace the accepted paper yet, even if you are its author. Open the PR on the website to discuss it or, as the corresponding author, accept it.

Add --ai-assisted to a push when AI helped prepare the text. Read the changes yourself before submitting them.

Publish a new note

Start in a directory outside any existing working copy. Choose a new folder name.

peerpedia init my-note --server https://peerpedia.dev
cd my-note

Write your note in paper.md. Fill in paper.json with a title, author names, abstract, and primary subject. Separate author names with \n inside the authors string. The following commands list subject codes and license choices.

peerpedia categories --server https://peerpedia.dev
peerpedia licenses --server https://peerpedia.dev

Read the license descriptions and put your chosen code in the license field. You must choose it yourself. Also accept the submission agreement on the website and use a token with permission to publish new papers.

{
  "title": "Symmetry through examples",
  "authors": "Ada Example\nSam Example",
  "abstract": "A short introduction to groups through rotations.",
  "primary_category": "math.GR",
  "secondary_categories": [],
  "license": "CC-BY-4.0"
}

Check the files and their preview in your editor before publishing.

peerpedia diff
peerpedia push -m "Initial publication"

An initial push publishes immediately. The first submission creates the public paper. Later pushes propose revisions for separate acceptance. Keep the same working-copy folder to continue editing that paper.

Work with chapters

For a paper with several pages, store each chapter in a Markdown file. List them in reading order in the chapters field of paper.json. The example below shows the fields to add alongside the paper’s title and other details.

"chapters": [
  {"id": "intro", "title": "Introduction", "file": "chapters/intro.md"},
  {"id": "examples", "title": "Examples", "file": "chapters/examples.md"}
],
"bibliography": "references.yaml"

Create the listed files inside your working-copy folder. The id is a stable name for a chapter. Keep it when renaming or reordering that chapter. The title is what readers see.

The bibliography is a shared BananaMark YAML file. See the citation example for its contents. Clone, diff, push, and pull include all chapters and the bibliography together.

Read feedback and fix the text

Overall reviews concern the whole paper. Passage feedback concerns a particular sentence, equation, or other part of the text. These commands read both from your working-copy folder.

peerpedia reviews --all
peerpedia feedback --all

--all fetches every page of results. The feedback list gives passage IDs and quotations. To read a passage’s complete discussion, replace PASSAGE_ID with its ID.

peerpedia discussion PASSAGE_ID --all

A passage can have several conversations. Each begins with a top-level comment, called a thread. The discussion output gives its thread ID. Read the replies as well as the first comment before deciding what to change.

After editing your files and checking the diff, you can link your proposal to the thread it addresses. Replace THREAD_ID with that thread’s ID, not the passage ID.

peerpedia push -m "Explain why compactness is needed" --address THREAD_ID --ai-assisted

Repeat --address to link more than one thread. Omit --ai-assisted if AI did not help prepare the change. A linked fix leaves the discussion open for its commenter to review.

Update a pending PR

A PR can contain several snapshots, each a fixed copy of the proposed paper. Updating the PR adds a snapshot without erasing earlier text or conversation. Only its newest snapshot can be accepted.

List the paper’s PRs, then inspect the one you want to continue. Replace PR_ID with its ID.

peerpedia prs --all
peerpedia pr PR_ID --all --json
peerpedia pr-comments PR_ID --all

The PR output includes its current head hash, a code for its newest snapshot. Save that full value for the update command. Start from the newest proposed text, retain the changes you intend to keep, and review your local diff.

peerpedia push -m "Add the example requested in review" --pr PR_ID --expected-head FULL_HEAD_HASH

Replace FULL_HEAD_HASH with the value you just read. This check prevents overwriting a newer PR update by accident. If it fails, read the new snapshot and reconcile your edits before trying again. You can update your own pending PR.

peerpedia snapshot SNAPSHOT_ID --server https://peerpedia.dev --json

Keep your copy up to date

After your PR is accepted

peerpedia pull

Pull downloads the latest accepted version. It refuses to overwrite local edits. A PR that is still pending is not included.

If another edit was accepted first

Your base is the accepted version you started editing. A stale_base message means the server has a newer accepted version. Fetch it without replacing your files.

peerpedia fetch

Compare your files with the incoming files named in the output. For a single-page paper, these are .peerpedia/incoming.md and .peerpedia/incoming-metadata.json. For chapters, look in the incoming folder. Edit your working files to keep the changes you need from both versions.

Once you have reconciled them, acknowledge the new base and inspect the result.

peerpedia rebase --acknowledge
peerpedia diff

Rebase records your decision. It does not merge the text for you. You can then push the revised proposal.

If a push loses its connection

If you do not know whether the server received a push, retry the saved request.

peerpedia push --retry

This sends the same saved submission without creating a duplicate. It sends that earlier copy even if you have edited your files since the failed attempt.

Use an AI assistant

The Peerpedia plugin for Codex helps find papers, read discussions, and prepare proposed changes. Its installation instructions are in the linked guide.

An assistant can work on the same local Markdown and bibliography as you. Adding --json to commands gives it structured results. Public reading needs no token. Submitting needs your token and follows the same PR process.

For a scripted runner, provide PEERPEDIA_TOKEN through its secret settings and set PEERPEDIA_SERVER to https://peerpedia.dev. Never put a token in a paper, prompt, or repository.

AI access to feedback is read-only. The CLI cannot post comments, rate papers or passages, vote, resolve discussions, accept a PR, or read private website drafts and inbox messages.

For more command options, run peerpedia --help or peerpedia push --help. The repository reference covers credential storage and verification in more detail.