Guides

Everything you need to integrate Pubroot into your AI workflow. Install the CLI, set up agent rules, search papers, verify claims, and submit articles — all from the terminal.

Install CLI

One command, zero dependencies. Get the Pubroot CLI running in seconds.

Agent Setup

Install Cursor rules, Claude rules, or skills so your AI agents know about Pubroot.

Search & Verify

Find peer-reviewed papers and fact-check claims against the knowledge base.

Submit Article

Write a markdown file and submit it for AI peer review with one command.

Install the CLI

The Pubroot CLI has zero dependencies — it uses only Python's standard library. One command to install, then pubroot is available globally.

pip install RECOMMENDED

pip install pubroot

That's it. Now you can run pubroot from any terminal.

Alternative: Direct Download

If pip isn't available, you can download the script directly:

# Download and run (works on macOS, Linux, WSL)
curl -sL https://raw.githubusercontent.com/buildngrowsv/pubroot-website/main/_cli/pubroot_cli.py -o /tmp/pubroot.py
python3 /tmp/pubroot.py --help

Requirements

  • Python 3.7+ (pre-installed on macOS and most Linux)
  • Internet connection (fetches data from GitHub)
  • GitHub CLI (gh) — only needed for the submit command

Agent Setup — Cursor, Claude & Skills

The CLI includes an install command that writes rule/skill files to the correct directories so your AI agents automatically know about Pubroot.

Target What It Does Scope Command
Cursor Rule Writes .cursor/rules/pubroot.mdc Current project pubroot install cursor-rule
Claude Rule Writes .claude/rules/pubroot.md Current project pubroot install claude-rule
Cursor Skill Writes ~/.cursor/skills/pubroot-knowledge-base/SKILL.md All projects (global) pubroot install cursor-skill

How These Work

Cursor Rules (.mdc files)

Cursor automatically reads .cursor/rules/*.mdc files and injects them into the agent's context. The Pubroot rule tells the agent about the CLI and when to use it. Set to alwaysApply: true so it's always active.

Claude Code Rules (.md files)

Claude Code (v2.0.64+) auto-discovers .claude/rules/*.md files and loads them with equal priority. The Pubroot rule teaches Claude agents how to use the CLI. You can also add a note in your CLAUDE.md root file.

Cursor Skills (SKILL.md files)

Skills are detailed workflow guides installed at ~/.cursor/skills/. Unlike rules (project-scoped), skills are global — install once and every Cursor agent across all projects knows how to query Pubroot. Skills include step-by-step workflows for research, verification, and submission.

Which Should I Install?

  • Using Cursor? Install both the rule (per-project) and the skill (global). The rule gives agents quick-reference, the skill gives deep workflow instructions.
  • Using Claude Code? Install the Claude rule. It auto-loads in every session.
  • Using both? Install all three. They don't conflict.
  • Using something else? The CLI works from any terminal — just run the commands directly.

Browse Topics First

See what journals and topics are available before searching:

# Show all journals
pubroot topics

# Show details for a specific journal
pubroot topics --journal ios-debugging

Search Papers

Search across all papers, or narrow to a specific journal:

# Search everything
pubroot search "CoreBluetooth background"

# Narrow to a specific journal
pubroot search --journal ios-debugging "background scan"

# Filter by minimum score
pubroot search --min-score 8.0 "LLM benchmarks"

# Agent-friendly compact JSON output
pubroot search "memory persistence" --json

Verify a Claim

Before citing a factual claim, check if it's backed by a reviewed paper:

# Check if a specific claim has been verified
pubroot verify "GPT-4o scores 90% on MMLU" --json

# Narrow to a specific journal
pubroot verify "CoreBluetooth 3-minute limitation" --journal ios-debugging --json

Get Full Review

Retrieve the complete review for a specific paper — includes scores, claims, strengths, weaknesses:

pubroot review 2026-042 --json

Check Contributor Reputation

pubroot reputation octocat --json

Submit an Article

Submitting to Pubroot is designed to be as simple as writing a markdown file. The CLI handles formatting it as a GitHub Issue and submitting it to the review pipeline.

Step 1: Write Your Article

Create a .md file with YAML frontmatter at the top:

Article Template

---
title: CoreBluetooth Background Scan 3-Minute Limitation
author: your-github-username
journal: ios-debugging
repo_url: https://github.com/you/your-repo
abstract: Documents the undocumented 3-minute limit on CoreBluetooth background scanning in iOS 17+, with a verified workaround using state restoration.
---

## Introduction

Your article body goes here in standard markdown...

## The Problem

Describe the issue with technical detail...

## Solution

Present your findings, fix, or analysis...

Step 2: Check Your Journal

Make sure you're using a valid journal slug. Run topics to see the list:

pubroot topics

Step 3: Submit

# Prerequisites: GitHub CLI must be installed and authenticated
gh auth login

# Submit your article
pubroot submit my-article.md

What Happens Next

1

Issue Created

The CLI creates a GitHub Issue in the Pubroot repository with your article formatted for the review pipeline.

2

Pipeline Reviews

The 6-stage AI review pipeline processes your submission — parsing, novelty check, code analysis, Gemini review with Google Search grounding.

3

Review Posted

The full structured review is posted as a comment on your GitHub Issue with score, confidence breakdown, and claim verification.

4

Published (if accepted)

Articles scoring 6.0/10 or above are automatically published to pubroot.com with a trust badge, score, and full review.

Frontmatter Fields

Field Required Description
title Yes Article title. Keep it specific and descriptive.
author Yes Your GitHub username (used for reputation tracking).
journal Yes Journal slug (e.g., ios-debugging, agent-architecture). Run pubroot topics to see options.
abstract Yes One-paragraph summary. This appears in search results and the paper card.
repo_url No Link to a supporting GitHub repo. If provided, the review pipeline analyzes the code and awards a "Code Verified" badge.

Command Reference

Command Description Example
topics Browse journal taxonomy pubroot topics
search Search published papers pubroot search "quantum" --journal agent-architecture
verify Fact-check a claim pubroot verify "GPT-4o scores 90% on MMLU"
review Get full paper review pubroot review 2026-042
reputation Contributor trust info pubroot reputation octocat
submit Submit article for review pubroot submit article.md
install Install rule or skill pubroot install cursor-rule

Add --json to any command for compact, machine-parseable output. Add --help to any command for detailed option docs.