{
  "markdown": "# Code of Paper CLI\n\nDiscover GitHub implementations of research papers — from the terminal.\n\nSearch 181k+ arXiv papers and find their code on GitHub. Works for humans and AI agents alike.\n\n[![PyPI](https://img.shields.io/pypi/v/codeofpaper)](https://pypi.org/project/codeofpaper/)\n[![Python 3.10+](https://img.shields.io/pypi/pyversions/codeofpaper)](https://pypi.org/project/codeofpaper/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n<!-- mcp-name: io.github.isagelswann/codeofpaper -->\n\n## Install\n\n```bash\npip install codeofpaper\n```\n\nOr with [pipx](https://pipx.pypa.io/) for isolated installs:\n\n```bash\npipx install codeofpaper\n```\n\nRequires Python 3.10+. No API key needed — works anonymously at 60 requests/minute.\n\n## Quick Start\n\n```bash\n# Search for papers\ncodeofpaper search \"vision transformers\"\n\n# Get paper details (arXiv IDs or full URLs both work)\ncodeofpaper paper 2010.11929\ncodeofpaper paper https://arxiv.org/abs/2010.11929\n\n# Find code implementations\ncodeofpaper code 1706.03762\n\n# Browse trending papers with code\ncodeofpaper trending --has-code\n\n# JSON output for scripts and agents\ncodeofpaper -o json trending | jq '.trending[] | {title, stars: .max_stars}'\n\n# One-shot reproducibility context for an agent: paper + confident repos\n# (with tier + framework + license) + fork-graph in a single JSON payload.\ncodeofpaper -o json paper 2010.11929 | jq '{title, repos: [.repos[] | {full_name, tier}], forks: [.fork_graph[] | .full_name]}'\n\n# Literature review in one command\ncodeofpaper research \"reinforcement learning\" --depth deep\n```\n\n## Output Formats\n\nUse `-o` / `--output` **before** the subcommand:\n\n```bash\ncodeofpaper -o json paper 2010.11929\ncodeofpaper -o quiet search \"attention\" | head -5\ncodeofpaper -o csv trending --has-code > papers.csv\n```\n\n| Format | Flag | Use case |\n|--------|------|----------|\n| Table | `-o table` | Human reading (default) |\n| JSON | `-o json` | Scripts, `jq` pipelines, full response data |\n| Quiet | `-o quiet` | IDs only, one per line — pipe into other commands |\n| JSONL | `-o jsonl` | Streaming, append to files, batch processing |\n| BibTeX | `-o bibtex` | Citation managers, LaTeX bibliographies |\n| CSV | `-o csv` | Spreadsheets, pandas, data analysis |\n\nThe shorthand `-q` is equivalent to `-o quiet`:\n\n```bash\ncodeofpaper -q search \"transformers\" | head -3\n```\n\nYou can set a default format via config so you don't need `-o` every time:\n\n```bash\ncodeofpaper auth setup    # then edit ~/.config/codeofpaper/config.json\n```\n\n## Commands\n\n### Discovery\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `search` | Full-text paper search | `codeofpaper search \"vision transformers\" --has-code` |\n| `paper` | Paper details by arXiv ID or URL | `codeofpaper paper 2010.11929` |\n| `code` | GitHub repos implementing a paper | `codeofpaper code 1706.03762` |\n| `similar` | Semantically similar papers | `codeofpaper similar 2010.11929` |\n| `suggest` | Autocomplete / quick lookup | `codeofpaper suggest \"attention\"` |\n| `random` | Random interesting paper | `codeofpaper random --quality high` |\n\n### Browsing\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `trending` | Trending papers by category | `codeofpaper trending --category cs.CV --sort hot` |\n| `categories` | List categories or get details | `codeofpaper categories cs.AI` |\n| `conferences` | List all conference series | `codeofpaper conferences` |\n| `conference` | Papers from a specific conference | `codeofpaper conference neurips_2024 --has-code` |\n| `code-drops` | Recent conference papers with new code | `codeofpaper code-drops --days 7` |\n| `repo` | Reverse lookup: repo → paper | `codeofpaper repo google-research/vision_transformer` |\n| `open` | Open paper or repo in browser | `codeofpaper open 2010.11929 --code` |\n\n### Bulk Operations\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `research` | Structured research overview | `codeofpaper research \"RL\" --depth deep` |\n| `batch` | Process multiple IDs from stdin/file | `cat ids.txt \\| codeofpaper batch paper` |\n| `export` | Paginated bulk export | `codeofpaper export trending -o csv > out.csv` |\n\n### Configuration\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `auth` | Manage API key (setup/status/clear) | `codeofpaper auth status` |\n| `status` | Check API health and stats | `codeofpaper status` |\n\n## Command Details\n\n### search\n\n```bash\ncodeofpaper search \"reinforcement learning\" --sort has_code --has-code\ncodeofpaper search \"GAN\" --limit 20 --offset 10\n```\n\nOptions: `--limit`, `--offset`, `--sort` (relevant, recent, has_code), `--has-code`, `--category`.\n\n### research\n\nMulti-step orchestrated overview of a research topic:\n\n```bash\ncodeofpaper research \"vision transformers\" --depth deep\n```\n\n| Depth | Steps | API calls |\n|-------|-------|-----------|\n| `shallow` | Search only + landscape statistics | 1 |\n| `medium` | Search + repos for top papers (default) | ~6 |\n| `deep` | Search + repos + similar papers from #1 | ~8 |\n\n### batch\n\nProcess multiple queries or IDs from a file or stdin. Always outputs JSONL regardless of `-o`:\n\n```bash\n# From a file\ncodeofpaper batch paper ids.txt\n\n# From stdin\necho -e \"2010.11929\\n1706.03762\" | codeofpaper batch paper\n\n# Pipe from another command\ncodeofpaper -q similar 2010.11929 | codeofpaper batch code\n```\n\nSupported commands: `paper`, `search`, `code`, `similar`, `suggest`.\n\nEach line produces one JSON object:\n```json\n{\"input\": \"2010.11929\", \"status\": \"ok\", \"data\": {...}}\n{\"input\": \"9999.99999\", \"status\": \"error\", \"error\": \"Not found\"}\n```\n\nOptions: `--delay` (seconds between calls, default 0.5).\n\n### export\n\nPaginated bulk export from trending, conference, or search:\n\n```bash\ncodeofpaper export trending --category cs.CV --has-code -o csv > cv.csv\ncodeofpaper export conference neurips_2024 --has-code -o bibtex > neurips.bib\ncodeofpaper export search \"transformers\" --max 500 -o jsonl > data.jsonl\n```\n\nAuto-paginates through results (100 per page, 0.5s delay). Options: `--max` (default 200), `--has-code`, `--category`, `--days`.\n\n## Agent Integration\n\nThe CLI is designed for AI agent consumption. Key features:\n\n### Stable Exit Codes\n\nAgents can branch on exit codes without parsing error messages:\n\n| Exit Code | Meaning | Agent Action |\n|-----------|---------|-------------|\n| 0 | Success | Parse stdout |\n| 1 | General error | Log and report |\n| 2 | Connection error | Retry with backoff |\n| 3 | Not found (404) | Skip or try different ID |\n| 4 | Rate limited (429) | Wait and retry |\n| 5 | Auth required (401/403) | Run `codeofpaper auth setup` |\n\n### Machine-Readable Output\n\n```bash\n# JSON for structured parsing\ncodeofpaper -o json paper 2010.11929 | jq '.title'\n\n# Quiet mode for ID lists\ncodeofpaper -q search \"attention\" | head -5\n\n# JSONL for streaming\ncodeofpaper -o jsonl trending --has-code | while read -r line; do\n  echo \"$line\" | jq -r '.arxiv_id'\ndone\n```\n\n### HTTP Cache\n\nResponses are cached on disk for 30 minutes (`~/.cache/codeofpaper/http/`), so repeated calls are instant and free.\n\n## MCP Server (optional)\n\nCode of Paper ships an optional [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes paper / code lookup as tools to any MCP-compatible agent — Claude Desktop, Cursor, Continue, Cline, Zed, etc.\n\nInstall with the `mcp` extra:\n\n```bash\npip install 'codeofpaper[mcp]'\n# or, with uv:\nuv tool install 'codeofpaper[mcp]'\n```\n\nThis adds a `codeofpaper-mcp` entry point that speaks MCP over stdio.\n\n### Wire into Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows), or `~/.config/Claude/claude_desktop_config.json` (Linux):\n\n```json\n{\n  \"mcpServers\": {\n    \"codeofpaper\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"codeofpaper[mcp]\", \"codeofpaper-mcp\"]\n    }\n  }\n}\n```\n\nThis pulls + runs the server on demand — no global install needed. If you've already `pip install`'d the package, you can replace the command with just `\"codeofpaper-mcp\"` and drop `args`.\n\n### Wire into Cursor / Continue / Cline\n\nMost MCP clients accept the same shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"codeofpaper\": {\n      \"command\": \"codeofpaper-mcp\",\n      \"env\": {\n        \"CODEOFPAPER_API_URL\": \"https://api.codeofpaper.com\"\n      }\n    }\n  }\n}\n```\n\n### Tools exposed\n\n| Tool | Purpose |\n|------|---------|\n| `paper_lookup(paper_id_or_url)` | Paper metadata + confident-tier repos |\n| `code_for_paper(paper_id_or_url, limit, include_possible)` | Ranked GitHub repos implementing a paper |\n| `search_papers(query, limit, year, venue, has_code)` | Free-text paper search with filters |\n\nAll tools are read-only, return plain JSON, and surface API errors as `{\"error\": \"...\", \"status\": N}` rather than throwing — agents get structured output either way.\n\n## Common Workflows\n\n### Core Discovery\n\n```bash\n# Find papers with code about a topic\ncodeofpaper search \"reinforcement learning\" --sort has_code --has-code\n\n# Get the best repo for a specific paper\ncodeofpaper code 1706.03762\n\n# Accepts arXiv URLs — no need to extract the ID\ncodeofpaper paper https://arxiv.org/abs/2010.11929\n\n# Reverse lookup: what paper does this repo implement?\ncodeofpaper repo google-research/vision_transformer\n\n# Open a paper in the browser, or jump straight to its code\ncodeofpaper open 2010.11929\ncodeofpaper open 2010.11929 --code\n```\n\n### Browsing & Monitoring\n\n```bash\n# What's trending in computer vision?\ncodeofpaper trending --category cs.CV --sort hot\n\n# Conference papers that just got new code\ncodeofpaper code-drops --days 7\n\n# NeurIPS 2024 oral papers with code\ncodeofpaper conference neurips_2024 --track oral --has-code\n\n# Daily monitoring: what's new in my field?\ncodeofpaper trending --category cs.CV --days 1 -o json >> ~/research/daily_cv.jsonl\n```\n\n### Composable Pipelines\n\n```bash\n# Find implementations of a paper's related work\ncodeofpaper similar 2010.11929 -o quiet | codeofpaper batch code\n\n# Batch process a reading list\ncat reading_list.txt | codeofpaper batch paper > enriched.jsonl\n\n# Cross-reference with GitHub CLI\ncodeofpaper code 1706.03762 -o quiet | head -1 | xargs gh repo view\n\n# Export conference papers as BibTeX\ncodeofpaper export conference neurips_2024 --has-code -o bibtex > neurips2024_code.bib\n\n# Bulk export a category for meta-analysis\ncodeofpaper export trending --category cs.CV --has-code --days 365 -o csv > cv_with_code.csv\n```\n\n### Multi-Step Scripts\n\n```bash\n# Find a paper → get top repo → clone it\nREPO=$(codeofpaper search \"attention is all you need\" -o quiet | head -1 | \\\n  xargs codeofpaper code -o json | jq -r '.top_repos[0].full_name')\ngh repo clone \"$REPO\"\n\n# Discover a random paper and explore its neighborhood\nID=$(codeofpaper random --quality high -o quiet)\ncodeofpaper paper \"$ID\"\ncodeofpaper similar \"$ID\"\ncodeofpaper code \"$ID\"\n\n# Quick paper lookup in a script\nARXIV_ID=\"2010.11929\"\nTITLE=$(codeofpaper -o json paper \"$ARXIV_ID\" | jq -r '.title')\necho \"Paper: $TITLE\"\n```\n\n## Configuration\n\nConfig is stored as JSON via [platformdirs](https://pypi.org/project/platformdirs/):\n\n| OS | Path |\n|----|------|\n| Linux | `~/.config/codeofpaper/config.json` |\n| macOS | `~/Library/Application Support/codeofpaper/config.json` |\n| Windows | `%APPDATA%\\codeofpaper\\config.json` |\n\nFields:\n\n```json\n{\n  \"api_url\": \"https://api.codeofpaper.com\",\n  \"api_key\": null,\n  \"default_format\": \"table\",\n  \"ca_bundle\": null\n}\n```\n\nNo config file needed — everything works out of the box with sensible defaults.\n\n### Priority Chain\n\nOptions are resolved in this order (first wins):\n\n1. CLI flag (`--api-url`, `--api-key`, `--ca-bundle`, `-o`)\n2. Environment variable (`CODEOFPAPER_API_URL`, `CODEOFPAPER_API_KEY`, `CODEOFPAPER_CA_BUNDLE`, `CODEOFPAPER_OUTPUT`, `CODEOFPAPER_TIMEOUT`)\n3. Config file\n4. Built-in defaults\n\n### Corporate Proxies / Custom TLS Certificates\n\nIf you're behind a corporate proxy that performs TLS inspection (man-in-the-middle), you'll see an SSL error like:\n\n```\nCannot reach API: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain\n```\n\nTo fix this, point the CLI at your corporate CA certificate bundle (PEM file). Three equivalent ways, in priority order:\n\n```bash\n# 1. CLI flag (per-invocation)\ncodeofpaper --ca-bundle /path/to/corporate-ca.pem search \"transformers\"\n\n# 2. Environment variable (per-session or in .bashrc/.zshrc)\nexport CODEOFPAPER_CA_BUNDLE=/path/to/corporate-ca.pem\n\n# 3. Config file (permanent — set once, forget)\n# Add to ~/.config/codeofpaper/config.json:\n#   {\"ca_bundle\": \"/path/to/corporate-ca.pem\"}\n```\n\nAsk your IT department for the CA certificate file if you don't have it.\n\n> **Tip:** If you've already set `SSL_CERT_FILE` for other tools (pip, curl, etc.), httpx respects that variable automatically — no extra configuration needed.\n\n## Alias: `cop`\n\nBoth `codeofpaper` and `cop` are installed as entry points:\n\n```bash\ncop search \"transformers\"\ncop -o json trending | jq '.'\n```\n\n> **Note:** If `cop` conflicts with another tool on your system, use `codeofpaper` instead.\n\n## Shell Completion\n\nInstall tab completion for your shell:\n\n```bash\ncodeofpaper --install-completion\n```\n\nSupports bash, zsh, fish, and PowerShell. After installing, restart your shell or source the completion file.\n\n## Help\n\n```bash\ncodeofpaper --help          # List all commands\ncodeofpaper search --help   # Help for a specific command\ncodeofpaper -v              # Print version\n```\n\n## Links\n\n- **Website:** https://codeofpaper.com\n- **API docs:** https://api.codeofpaper.com/docs\n- **Agent discovery:** https://codeofpaper.com/llms.txt\n\n## License\n\nMIT\n",
  "bytes": 13732,
  "sha": "10758fc4517b798ad68032757265c44280b26e1facd2d0147d7a0b260914ff26",
  "repo_slug": "isagelswann/codeofpaper-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_isagelswann_codeofpaper_aed30381/readme"
}