paperhound 0.1.0__tar.gz

paperhound-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+.venv/
+.env
+.env.*
+
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+dist/
+build/
+*.egg-info/
+
+.vscode/
+.idea/
+.DS_Store

paperhound-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Fernández Camello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paperhound-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: paperhound
+Version: 0.1.0
+Summary: CLI to search, download, and convert academic papers (arXiv, Semantic Scholar) into Markdown — built for AI/ML researchers.
+Project-URL: Homepage, https://github.com/alexfdez1010/paperhound
+Project-URL: Repository, https://github.com/alexfdez1010/paperhound
+Project-URL: Issues, https://github.com/alexfdez1010/paperhound/issues
+Author-email: Alejandro Fernández Camello <alejandrofernandezcamello@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Alejandro Fernández Camello
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: academic,arxiv,cli,docling,machine-learning,markdown,papers,phd,research,semantic-scholar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: arxiv>=2.1.3
+Requires-Dist: docling>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paperhound
+
+[![PyPI](https://img.shields.io/pypi/v/paperhound.svg)](https://pypi.org/project/paperhound/)
+[![Python versions](https://img.shields.io/pypi/pyversions/paperhound.svg)](https://pypi.org/project/paperhound/)
+[![License](https://img.shields.io/pypi/l/paperhound.svg)](LICENSE)
+
+> **paperhound** — sniff out academic papers from the command line.
+
+A small, fast CLI for AI/ML researchers who want a single tool to **search**,
+**inspect**, **download**, and **convert to Markdown** papers from arXiv and
+Semantic Scholar. Conversion is powered by [docling](https://github.com/docling-project/docling),
+so the resulting Markdown is good enough to feed straight into an LLM context.
+
+## Features
+
+- 🔎 **Unified search** — one query, all backends. arXiv and Semantic Scholar
+  are queried in parallel and the results are merged and deduplicated.
+- 📄 **Inspect before downloading** — `paperhound show <id>` prints the
+  abstract and metadata so you can decide if it's worth a download.
+- ⬇️ **Download by identifier** — arXiv id, DOI, Semantic Scholar paper id, or
+  any paper URL. Open-access PDFs are resolved automatically.
+- 📝 **PDF → Markdown via docling** — `paperhound convert paper.pdf` or
+  `paperhound get <id>` for the full pipeline.
+- 🤖 **Agent-ready** — ships with a `SKILL.md` and JSON output mode so any
+  Claude / OpenAI / local agent can drive the CLI.
+- 🧪 **Heavily tested** — every module has unit tests; live integration tests
+  are gated behind an environment variable.
+
+## Installation
+
+```bash
+pip install paperhound
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install paperhound
+```
+
+Python 3.10+ is required. Docling pulls in PyTorch on first run, so the very
+first conversion may take a moment to download model weights.
+
+## Quick start
+
+```bash
+# Search across all providers
+paperhound search "diffusion transformers" --limit 5
+
+# Show the abstract for a specific paper
+paperhound show 2401.12345
+paperhound show 10.1038/s41586-020-2649-2          # DOI works too
+paperhound show https://arxiv.org/abs/1706.03762   # ...and URLs
+
+# Download the PDF
+paperhound download 1706.03762 -o ./papers/
+
+# Convert a local PDF to Markdown
+paperhound convert ./papers/1706.03762.pdf -o attention.md
+
+# Or do it all at once: search-resolve, download, convert, clean up
+paperhound get 1706.03762 -o attention.md
+```
+
+### JSON output for scripts and agents
+
+```bash
+paperhound search "graph neural networks" --json | jq '.[].title'
+paperhound show 1706.03762 --json
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `paperhound search <query>` | Run a unified search. `--limit`, `--source arxiv\|semantic_scholar`, `--year-min`, `--year-max`, `--json`. |
+| `paperhound show <id>` | Fetch a paper's metadata + abstract. |
+| `paperhound download <id> -o <path>` | Download a paper PDF. |
+| `paperhound convert <pdf> -o <md>` | Convert a PDF (or any docling-supported file/URL) to Markdown. |
+| `paperhound get <id> -o <md>` | Download + convert in one step. `--keep-pdf` to keep the PDF. |
+| `paperhound version` | Print the installed version. |
+
+Run `paperhound <command> --help` for full options.
+
+## Identifier formats
+
+paperhound accepts whatever you have on hand:
+
+- arXiv ids: `2401.12345`, `2401.12345v3`, `cs.AI/0301001`, `arXiv:2401.12345`
+- DOIs: `10.1038/s41586-020-2649-2`, `doi:10.1038/...`
+- Semantic Scholar paper ids: 40-char hex
+- URLs: `arxiv.org/abs/...`, `arxiv.org/pdf/...`, `doi.org/...`,
+  `semanticscholar.org/paper/...`
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `SEMANTIC_SCHOLAR_API_KEY` | Optional. Lifts the public rate limit for the Semantic Scholar Graph API. |
+| `PAPERHOUND_RUN_INTEGRATION` | Set to `1` to run live integration tests. |
+
+## Use it from agents
+
+paperhound is designed to be driven by AI agents. The repo includes a ready-to-install
+[skill at `skills/paperhound/SKILL.md`](skills/paperhound/SKILL.md) that documents
+every command, recommends the JSON output flag, and gives an end-to-end example.
+Drop the skill into your agent's skill directory (e.g. `~/.claude/skills/`) and
+the agent will know how to search papers, fetch abstracts, and produce Markdown.
+
+## Development
+
+```bash
+make install            # uv sync --extra dev
+make test               # unit tests
+make test-integration   # live API tests (PAPERHOUND_RUN_INTEGRATION=1)
+make check              # lint + format check + tests (run before pushing)
+```
+
+The test suite uses `respx` to record/replay HTTP, so unit tests do not touch
+the network. Provider clients are dependency-injected, which makes the
+aggregator and CLI fully unit-testable.
+
+## Releasing to PyPI
+
+1. Bump `version` in `pyproject.toml` and `paperhound/__init__.py`.
+2. Tag the release: `git tag v0.1.1 && git push --tags`.
+3. The `Publish to PyPI` GitHub Action builds and publishes via
+   [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no
+   API token required, just configure the trusted publisher once on PyPI.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

paperhound-0.1.0/README.md

@@ -0,0 +1,133 @@
+# paperhound
+
+[![PyPI](https://img.shields.io/pypi/v/paperhound.svg)](https://pypi.org/project/paperhound/)
+[![Python versions](https://img.shields.io/pypi/pyversions/paperhound.svg)](https://pypi.org/project/paperhound/)
+[![License](https://img.shields.io/pypi/l/paperhound.svg)](LICENSE)
+
+> **paperhound** — sniff out academic papers from the command line.
+
+A small, fast CLI for AI/ML researchers who want a single tool to **search**,
+**inspect**, **download**, and **convert to Markdown** papers from arXiv and
+Semantic Scholar. Conversion is powered by [docling](https://github.com/docling-project/docling),
+so the resulting Markdown is good enough to feed straight into an LLM context.
+
+## Features
+
+- 🔎 **Unified search** — one query, all backends. arXiv and Semantic Scholar
+  are queried in parallel and the results are merged and deduplicated.
+- 📄 **Inspect before downloading** — `paperhound show <id>` prints the
+  abstract and metadata so you can decide if it's worth a download.
+- ⬇️ **Download by identifier** — arXiv id, DOI, Semantic Scholar paper id, or
+  any paper URL. Open-access PDFs are resolved automatically.
+- 📝 **PDF → Markdown via docling** — `paperhound convert paper.pdf` or
+  `paperhound get <id>` for the full pipeline.
+- 🤖 **Agent-ready** — ships with a `SKILL.md` and JSON output mode so any
+  Claude / OpenAI / local agent can drive the CLI.
+- 🧪 **Heavily tested** — every module has unit tests; live integration tests
+  are gated behind an environment variable.
+
+## Installation
+
+```bash
+pip install paperhound
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install paperhound
+```
+
+Python 3.10+ is required. Docling pulls in PyTorch on first run, so the very
+first conversion may take a moment to download model weights.
+
+## Quick start
+
+```bash
+# Search across all providers
+paperhound search "diffusion transformers" --limit 5
+
+# Show the abstract for a specific paper
+paperhound show 2401.12345
+paperhound show 10.1038/s41586-020-2649-2          # DOI works too
+paperhound show https://arxiv.org/abs/1706.03762   # ...and URLs
+
+# Download the PDF
+paperhound download 1706.03762 -o ./papers/
+
+# Convert a local PDF to Markdown
+paperhound convert ./papers/1706.03762.pdf -o attention.md
+
+# Or do it all at once: search-resolve, download, convert, clean up
+paperhound get 1706.03762 -o attention.md
+```
+
+### JSON output for scripts and agents
+
+```bash
+paperhound search "graph neural networks" --json | jq '.[].title'
+paperhound show 1706.03762 --json
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `paperhound search <query>` | Run a unified search. `--limit`, `--source arxiv\|semantic_scholar`, `--year-min`, `--year-max`, `--json`. |
+| `paperhound show <id>` | Fetch a paper's metadata + abstract. |
+| `paperhound download <id> -o <path>` | Download a paper PDF. |
+| `paperhound convert <pdf> -o <md>` | Convert a PDF (or any docling-supported file/URL) to Markdown. |
+| `paperhound get <id> -o <md>` | Download + convert in one step. `--keep-pdf` to keep the PDF. |
+| `paperhound version` | Print the installed version. |
+
+Run `paperhound <command> --help` for full options.
+
+## Identifier formats
+
+paperhound accepts whatever you have on hand:
+
+- arXiv ids: `2401.12345`, `2401.12345v3`, `cs.AI/0301001`, `arXiv:2401.12345`
+- DOIs: `10.1038/s41586-020-2649-2`, `doi:10.1038/...`
+- Semantic Scholar paper ids: 40-char hex
+- URLs: `arxiv.org/abs/...`, `arxiv.org/pdf/...`, `doi.org/...`,
+  `semanticscholar.org/paper/...`
+
+## Configuration
+
+| Env var | Purpose |
+|---|---|
+| `SEMANTIC_SCHOLAR_API_KEY` | Optional. Lifts the public rate limit for the Semantic Scholar Graph API. |
+| `PAPERHOUND_RUN_INTEGRATION` | Set to `1` to run live integration tests. |
+
+## Use it from agents
+
+paperhound is designed to be driven by AI agents. The repo includes a ready-to-install
+[skill at `skills/paperhound/SKILL.md`](skills/paperhound/SKILL.md) that documents
+every command, recommends the JSON output flag, and gives an end-to-end example.
+Drop the skill into your agent's skill directory (e.g. `~/.claude/skills/`) and
+the agent will know how to search papers, fetch abstracts, and produce Markdown.
+
+## Development
+
+```bash
+make install            # uv sync --extra dev
+make test               # unit tests
+make test-integration   # live API tests (PAPERHOUND_RUN_INTEGRATION=1)
+make check              # lint + format check + tests (run before pushing)
+```
+
+The test suite uses `respx` to record/replay HTTP, so unit tests do not touch
+the network. Provider clients are dependency-injected, which makes the
+aggregator and CLI fully unit-testable.
+
+## Releasing to PyPI
+
+1. Bump `version` in `pyproject.toml` and `paperhound/__init__.py`.
+2. Tag the release: `git tag v0.1.1 && git push --tags`.
+3. The `Publish to PyPI` GitHub Action builds and publishes via
+   [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) — no
+   API token required, just configure the trusted publisher once on PyPI.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

paperhound-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[project]
+name = "paperhound"
+version = "0.1.0"
+description = "CLI to search, download, and convert academic papers (arXiv, Semantic Scholar) into Markdown — built for AI/ML researchers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Alejandro Fernández Camello", email = "alejandrofernandezcamello@gmail.com" },
+]
+keywords = [
+    "arxiv",
+    "semantic-scholar",
+    "papers",
+    "research",
+    "cli",
+    "docling",
+    "markdown",
+    "academic",
+    "machine-learning",
+    "phd",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.7.0",
+    "httpx>=0.27.0",
+    "arxiv>=2.1.3",
+    "docling>=2.0.0",
+    "pydantic>=2.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/alexfdez1010/paperhound"
+Repository = "https://github.com/alexfdez1010/paperhound"
+Issues = "https://github.com/alexfdez1010/paperhound/issues"
+
+[project.scripts]
+paperhound = "paperhound.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "respx>=0.21.0",
+    "ruff>=0.6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paperhound"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/paperhound", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+addopts = "-v"
+testpaths = ["tests"]
+markers = [
+    "integration: tests that hit live APIs (deselect with '-m \"not integration\"')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.flake8-bugbear]
+# Typer relies on typer.Argument()/typer.Option() in defaults; that is the
+# documented API, not a bug.
+extend-immutable-calls = [
+    "typer.Argument",
+    "typer.Option",
+]

paperhound-0.1.0/src/paperhound/__init__.py

@@ -0,0 +1,7 @@
+"""paperhound — search, download, and convert academic papers from the command line."""
+
+from paperhound.models import Author, Paper, PaperIdentifier
+
+__version__ = "0.1.0"
+
+__all__ = ["Author", "Paper", "PaperIdentifier", "__version__"]

paperhound-0.1.0/src/paperhound/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m paperhound`` to run the CLI."""
+
+from paperhound.cli import app
+
+if __name__ == "__main__":
+    app()

paperhound-0.1.0/src/paperhound/cli.py

@@ -0,0 +1,213 @@
+"""paperhound command-line interface."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from paperhound import __version__
+from paperhound.convert import convert_to_markdown
+from paperhound.download import download_pdf, resolve_pdf_url
+from paperhound.errors import PaperhoundError
+from paperhound.identifiers import IdentifierKind, detect
+from paperhound.output import papers_to_json, render_paper_detail, render_table
+from paperhound.search import (
+    ArxivProvider,
+    SearchAggregator,
+    SearchQuery,
+    SemanticScholarProvider,
+)
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Search, download, and convert academic papers from the command line.",
+)
+
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _build_aggregator(sources: list[str] | None = None) -> SearchAggregator:
+    chosen = {s.lower() for s in sources} if sources else {"arxiv", "semantic_scholar"}
+    providers = []
+    if "arxiv" in chosen:
+        providers.append(ArxivProvider())
+    if "semantic_scholar" in chosen or "s2" in chosen:
+        providers.append(SemanticScholarProvider())
+    if not providers:
+        raise typer.BadParameter(f"Unknown sources: {sources!r}")
+    return SearchAggregator(providers)
+
+
+def _exit_on_error(exc: Exception) -> None:
+    err_console.print(f"[red]error:[/red] {exc}")
+    raise typer.Exit(code=1)
+
+
+@app.callback()
+def _root(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable verbose logging."),
+) -> None:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+
+@app.command()
+def version() -> None:
+    """Print the installed paperhound version."""
+    console.print(__version__)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Free-text query."),
+    limit: int = typer.Option(10, "--limit", "-n", min=1, max=100),
+    source: list[str] | None = typer.Option(
+        None,
+        "--source",
+        "-s",
+        help="Restrict to a provider (arxiv, semantic_scholar). Repeatable.",
+    ),
+    year_min: int | None = typer.Option(None, "--year-min"),
+    year_max: int | None = typer.Option(None, "--year-max"),
+    json_output: bool = typer.Option(False, "--json", help="Emit JSON instead of a table."),
+) -> None:
+    """Search across all providers and print the merged results."""
+    aggregator = _build_aggregator(source)
+    try:
+        papers = aggregator.search(
+            SearchQuery(
+                text=query,
+                limit=limit,
+                year_min=year_min,
+                year_max=year_max,
+            )
+        )
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return
+
+    if not papers:
+        err_console.print("[yellow]No results.[/yellow]")
+        raise typer.Exit(code=0)
+
+    if json_output:
+        sys.stdout.write(papers_to_json(papers) + "\n")
+    else:
+        render_table(papers, console)
+
+
+@app.command()
+def show(
+    identifier: str = typer.Argument(..., help="arXiv id, DOI, S2 id, or paper URL."),
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
+    """Fetch a paper's metadata and abstract."""
+    aggregator = _build_aggregator()
+    try:
+        paper = aggregator.get(identifier)
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return
+
+    if paper is None:
+        err_console.print(f"[yellow]Not found:[/yellow] {identifier}")
+        raise typer.Exit(code=1)
+
+    if json_output:
+        sys.stdout.write(paper.model_dump_json(indent=2) + "\n")
+    else:
+        render_paper_detail(paper, console)
+
+
+def _lookup_pdf_url(identifier: str) -> str | None:
+    """Aggregator-backed callback used by ``download`` for non-arXiv ids."""
+    aggregator = _build_aggregator()
+    paper = aggregator.get(identifier)
+    return paper.pdf_url if paper else None
+
+
+@app.command()
+def download(
+    identifier: str = typer.Argument(..., help="arXiv id, DOI, S2 id, or paper URL."),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Destination file or directory. Defaults to the current directory.",
+    ),
+) -> Path:
+    """Download a paper PDF."""
+    destination = output if output is not None else Path.cwd()
+    try:
+        url = resolve_pdf_url(identifier, lookup_pdf_url=_lookup_pdf_url)
+        path = download_pdf(url, destination)
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return Path()
+    console.print(f"[green]Saved[/green] {path}")
+    return path
+
+
+@app.command()
+def convert(
+    source: str = typer.Argument(..., help="Path or URL to a PDF / supported document."),
+    output: Path | None = typer.Option(None, "--output", "-o"),
+) -> None:
+    """Convert a document to Markdown via docling."""
+    try:
+        markdown = convert_to_markdown(source, output=output)
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return
+
+    if output is None:
+        sys.stdout.write(markdown)
+    else:
+        console.print(f"[green]Wrote[/green] {output}")
+
+
+@app.command()
+def get(
+    identifier: str = typer.Argument(..., help="arXiv id, DOI, S2 id, or paper URL."),
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Markdown output path. Defaults to <id>.md in the current directory.",
+    ),
+    keep_pdf: bool = typer.Option(False, "--keep-pdf", help="Keep the downloaded PDF."),
+) -> None:
+    """Download a paper and convert it to Markdown in one step."""
+    try:
+        kind, value = detect(identifier)
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return
+
+    md_default_stem = value.replace("/", "_") if kind is IdentifierKind.ARXIV else value
+    md_path = output or Path.cwd() / f"{md_default_stem}.md"
+    pdf_dest = (md_path.parent if keep_pdf else Path.cwd()) / f"{md_default_stem}.pdf"
+
+    try:
+        url = resolve_pdf_url(identifier, lookup_pdf_url=_lookup_pdf_url)
+        pdf_path = download_pdf(url, pdf_dest)
+        convert_to_markdown(pdf_path, output=md_path)
+    except PaperhoundError as exc:
+        _exit_on_error(exc)
+        return
+    finally:
+        if not keep_pdf and pdf_dest.exists():
+            try:
+                pdf_dest.unlink()
+            except OSError:
+                pass
+
+    console.print(f"[green]Wrote[/green] {md_path}")