pwc-cli

# pwc CLI, Skill, and MCP server A fast command-line client for exploring and editing the [Papers with Code](https://paperswithcode.co) catalog, alongside a Skill for coding agents and a hosted Model Context Protocol server. ## MCP server The [`mcp_server`](mcp_server) package exposes an anonymous, read-only, agent-native interface over Streamable HTTP. It supports MCP `2026-07-28` and legacy 2025-era clients from one endpoint, with one tool per `pwc` research command: papers, related work, lineage, tasks, methods, conferences, organizations, frameworks, benchmarks, and filtered leaderboard evaluations. Run it locally with: ```bash uv run --project mcp_server pwc-mcp ``` See [`mcp_server/README.md`](mcp_server/README.md) for tools, resources, configuration, security limits, and hosting details. Let your coding agent use `pwc` to: - search papers - browse benchmarks and find state-of-the-art (SOTA) by domain - read paper metadata and Markdown - discover recent, trending, and related work - inspect paper lineage (follow-up work and predecessors) - explore tasks, methods, conferences, organizations, and frameworks. Public reads are anonymous: no account, API token, or Python environment is required. ```bash pwc search "small vision language models" --limit 3 pwc paper info 2501.01234 ``` It's recommended to also install the Skill so your coding agent knows how to use the CLI. ## Installation ### Prebuilt binary (recommended) The installer downloads the binary for your platform, verifies its SHA-256 checksum, and installs it as `~/.local/bin/pwc`: ```bash pwc_repo=https://raw.githubusercontent.com/huggingface/pwc-cli/main curl -LsSf "$pwc_repo/standalone_cli/install.py" | python3 ``` The installer selects the latest release by default. Pass `--version VERSION` after `python3 -` to explicitly pin a release. It also reports whether `~/.local/bin` is on `PATH` and prints a persistent shell instruction when needed. Prebuilt releases support: - Linux x86-64 - macOS Intel (x86-64) - macOS Apple Silicon (arm64) Every release includes checksum files and GitHub build-provenance attestations. See the [latest release](https://github.com/huggingface/pwc-cli/releases/latest) to download and verify an artifact manually. ### Install from source Python 3.10 or newer is required for source installations. With [`uv`](https://docs.astral.sh/uv/): ```bash uv tool install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli' ``` Or with [`pipx`](https://pipx.pypa.io/): ```bash pipx install 'git+https://github.com/huggingface/pwc-cli.git#subdirectory=standalone_cli' ``` To work from a clone instead: ```bash git clone https://github.com/huggingface/pwc-cli.git cd pwc-cli uv tool install ./standalone_cli ``` Confirm the installation: ```bash pwc version ``` ## Add the CLI Skill Skills give coding agents the context they need to choose and use `pwc` commands effectively. The Skill is generated by your locally installed CLI, so it matches that CLI version. ```bash # Install for this project. Works with Codex, Cursor, OpenCode, and other # agents that load Skills from .agents/skills. pwc skills add # Install for all projects in ~/.agents/skills. pwc skills add --global # Also make the Skill available to Claude Code. pwc skills add --claude pwc skills add --claude --global ``` For another coding-agent harness, pass its Skills directory explicitly: ```bash pwc skills add --dest /path/to/skills ``` An existing installation is left untouched. Use `--force` to replace it with the Skill generated by the currently installed CLI. ## Quick start Search the paper catalog: ```bash pwc search "retrieval augmented generation" pwc search "vision transformers" --mode semantic --limit 20 pwc search "attention" --page 2 --limit 10 pwc search "attention" --has-official-implementation ``` Inspect or read a paper: ```bash pwc paper info 1706.03762 # includes tagged organizations pwc paper info 1706.03762 --include-resources # linked GitHub, project, and HF URLs pwc paper info 1706.03762 --include-evals # evaluation Markdown table pwc paper info "Attention Is All You Need" pwc paper read 1706.03762 ``` Discover papers: ```bash pwc paper recent --limit 10 pwc paper recent --implementation-coverage pwc paper trending --limit 20 --max-age-days 90 pwc paper related 1706.03762 --limit 4 pwc paper lineage list 1706.03762 ``` List and filter papers: ```bash pwc paper list --conference NeurIPS --page-size 20 pwc paper list --organization Qwen --order-by date_published pwc paper list --author "Kaiming He" --search drift --order-by date_published pwc paper list --task "Image Classification" --method Transformer pwc paper list --conference "CVPR 2026" --framework PyTorch pwc paper list --search "diffusion" --start-date 2025-01-01 --end-date 2025-01-31 pwc paper list --order-by citation_count --order-dir desc pwc paper list --has-official-implementation --implementation-coverage ``` Explore the research taxonomy and conferences: ```bash pwc task list pwc task list --area Vision pwc task list --group-by-area # force grouped Markdown when piping/capturing pwc task --name "scene-text-recognition" pwc method --name Transformer pwc method list --area Audio pwc method list --area General --introduced-year 2017 pwc conference --name "CVPR 2025" pwc conference list pwc conference list --year 2025 pwc organization --name NVIDIA pwc organization list --featured-only pwc framework --name vLLM pwc framework list --platform gpu ``` Browse benchmarks: ```bash pwc benchmark list pwc benchmark list --group-by-area --area Vision pwc benchmark list --search ImageNet pwc benchmark list --task OCR pwc benchmark list --task image-classification --include-descendants pwc benchmark list --min-eval-count 10 --order-by paper_count --order-dir desc pwc benchmark --name "SWE-Bench Pro" pwc benchmark --name wikitext-103 --is-open true --max-parameters 3B ``` ## Command reference Every `PAPER` argument accepts a modern or legacy arXiv ID, a numeric external-paper ID, or a quoted exact paper title. Title matching is case-insensitive. Ambiguous titles are rejected with the matching IDs instead of silently selecting one paper. | Command | Description | | --- | --- | | `pwc search QUERY` | Search for papers by title, topic, author, or arXiv ID | | `pwc paper info PAPER` | Show paper metadata, abstract, predecessors, and successors; optionally include resources or an evaluation Markdown table | | `pwc paper read PAPER` | Print the stored paper Markdown | | `pwc paper list` | List and filter papers | | `pwc paper recent` | List recently published papers | | `pwc paper trending` | List trending papers | | `pwc paper related PAPER` | Find related papers | | `pwc paper lineage list PAPER` | Show linked Markdown sections for a paper's predecessors and successors | | `pwc task list` | Group tasks by area with paper, benchmark, and evaluation counts; support flat pagination and area filters | | `pwc task --name NAME` | Show task-page details, including frameworks, sister tasks, common methods, benchmarks, and papers | | `pwc method --name NAME` | Show details for an exact method name, full name, slug, or ID | | `pwc method list` | List methods and filter them by research area or introduction year | | `pwc conference --name NAME` | Show details for an exact conference name, slug, or ID | | `pwc conference list` | List conferences and filter them by year | | `pwc organization --name NAME` | Show details for an exact organization name, slug, or ID | | `pwc organization list` | List organizations, optionally restricting to featured organizations | | `pwc framework --name NAME` | Show details for an exact framework name, slug, or ID | | `pwc framework list` | List frameworks by domain, category, or platform | | `pwc benchmark list` | Group top benchmarks by area and task; support flat filters and task-trend ranking | | `pwc benchmark --name NAME` | Show a benchmark's top models, parameter counts, papers, scores, and publication dates; optionally apply an inclusive model-size limit | | `pwc skills add` | Install the version-matched Skill for coding agents | | `pwc version` | Show the CLI and API contract versions | Run `pwc --help`, `pwc COMMAND --help`, or `pwc paper COMMAND --help` for all available options. ## Output and scripting Task and benchmark lists use grouped Markdown in an interactive terminal; `--flat` forces their paginated tables and `--group-by-area` forces Markdown when piping. Flat benchmark lists use aligned columns in both terminals and captured output; use `--json` for machine-readable benchmark rows. Other list and search commands use aligned columns in a terminal and lossless TSV when captured. Benchmark details use an aligned table in a terminal and Markdown when piped or captured. Other detail commands use labeled metadata or Markdown. Paper discovery commands accept `--implementation-coverage` to add official-code status and the total linked repository count; JSON and `pwc paper info` always include them. A false official-code status only means the catalog has no linked official repository. Search and paper-list filters using `--has-official-implementation` fail closed unless the API confirms the filter. Add `--json` to any data command for machine-readable output: ```bash pwc search "language models" --limit 5 --json pwc paper info 1706.03762 --include-evals --json pwc benchmark list --task image-classification --json ``` JSON responses include a top-level `schema_version` and `data` field: ```json { "schema_version": "v1", "data": {} } ``` The stable exit codes are: | Code | Meaning | | ---: | --- | | `0` | Success | | `2` | Invalid command or arguments | | `3` | Network or server failure | | `4` | Invalid API response | ## Configuration `pwc` uses `https://paperswithcode.co/api/v1` by default. To connect to another compatible v1 API, set `PWC_API_URL`: ```bash PWC_API_URL=http://localhost:8000/api/v1 pwc search "transformers" ``` ## Scope Public catalog commands are anonymous and read-only. Paper editing is an explicit authenticated workflow scoped to one confirmed paper; the CLI does not include general ingestion, image, embedding, CRON, or infrastructure maintenance commands. ## Development Run the CLI from a checkout: ```bash uv run --project standalone_cli pwc --help ``` Run the focused test and contract checks: ```bash uv run --project standalone_cli --with pytest pytest standalone_cli/tests uv run python standalone_cli/scripts/check_contract.py ``` The implementation lives in [`standalone_cli`](standalone_cli/). ## Edit a paper with your agent Requires a server with the paper-edit API enabled. Sign in using the browser link and confirm the paper and code. This grants one hour of write access to that paper; each batch publishes immediately under your HF username. ```bash pwc auth login --paper 123 # --no-browser for remote machines pwc paper edit export 123 --output edits.json # Add explicit operations to edits.json; current is reference material. pwc paper edit preview 123 --file edits.json pwc paper edit submit 123 --file edits.json pwc auth status --paper 123 pwc auth logout --paper 123 ``` For example, add the following to the exported `operations` array, substituting real existing task/dataset/metric identifiers. A metrics dictionary lets you submit multiple scores without repeating model and benchmark details: ```json { "section": "evaluations", "payload": { "task_id": 1, "dataset_id": 2, "model_name": "Example model", "methodology": "Test split, zero-shot; Table 3", "metrics": {"Accuracy": 90.5, "F1": 88.1}, "source_url": "https://arxiv.org/abs/2601.00001" } } ``` Add `evaluation_id` alongside `section` to correct a row. Other supported sections are tasks, methods, repositories, project_pages, hf_artifacts, x_threads, and source_url. `x_threads` takes `{"x_threads": [post URLs]}` in display order (at most 10); link only posts in which the paper's authors or their organization introduce the paper. Section replacements must retain unrelated entries. Evaluation updates preserve omitted fields. Existing benchmark/metric definitions are required; evaluation deletion and rank overrides are excluded. Batches contain at most 50 operations and 1 MiB. Invalid or stale batches write nothing. Retry uncertain network results with the exact same document and idempotency key. For a stale revision, export again and reconcile before retrying. Accounts share a 20-distinct-paper daily limit (UTC) and 30-publication-per-minute limit across the website and CLI; admins are exempt. `pwc skills add --force` installs the detailed agent workflow. Credentials are stored in mode-0600 files inside the mode-0700 directory `~/.config/pwc/edit-credentials`, keyed by API base URL and paper. Never copy these files into prompts or repositories. `PWC_API_URL` selects the target API; editing requires HTTPS, except on loopback development servers, and refuses redirects. Public read commands never load edit credentials.