# CLI Reference

## Global Options

```
axm-bib --help       Show help
axm-bib --version    Show version
```

## `search` — Search Papers

```
axm-bib search [OPTIONS] QUERY
```

| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `QUERY` | | string | *required* | Search query (title, keywords) |
| `--limit` | `-n` | int | 10 | Max results (1–100, clamped) |
| `--abstract/--no-abstract` | | bool | `True` | Show abstracts |
| `--abstract-len` | | int | 0 | Truncate to N chars (0 = full) |

**Validation rules:**

- `limit` < 1 → error
- `limit` > 100 → clamped to 100
- Empty query → error

**Example:**

```bash
axm-bib search "loop invariants" -n 10 --abstract-len 150
```

---

## `resolve` — Resolve Identifiers to BibTeX

```
axm-bib resolve ID [ID ...]
```

| Option | Type | Description |
|---|---|---|
| `ID [ID ...]` | string(s) | One or more identifiers: DOI, arXiv ID, HAL ID, DBLP key, or OpenReview URL |

Auto-detects each identifier type and routes to the appropriate client. Multiple IDs for the same paper are merged with a coherence check.

**Supported formats:**

- DOI: `10.1145/363235.363259`
- arXiv: `arXiv:1706.03762`, `https://arxiv.org/abs/1706.03762`
- HAL: `hal-01234567`
- DBLP: `conf/nips/VaswaniSPUJGKP17`
- OpenReview: `https://openreview.net/forum?id=...` or `openreview:ID`

!!! warning "Titles are rejected"
    Pass identifiers only. Titles produce an error with a hint to use `axm-bib search`.

**Examples:**

```bash
# Single identifier
axm-bib resolve "arXiv:1706.03762"
axm-bib resolve "10.1145/363235.363259"

# Multi-ref merge (same paper, different IDs)
axm-bib resolve "10.1234/test" "arXiv:2503.18813"
```

---

## `graph` — Citation Graph Traversal

```
axm-bib graph [OPTIONS] PAPER_ID
```

| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `PAPER_ID` | | string | *required* | Paper ID (DOI, arXiv ID, or S2 paper ID) |
| `--direction` | `-d` | string | `citations` | `citations`, `references`, or `similar` |
| `--limit` | `-n` | int | 20 | Max results |
| `--abstract/--no-abstract` | | bool | `True` | Show abstracts |
| `--abstract-len` | | int | 0 | Truncate to N chars (0 = full) |

**Data sources:** Semantic Scholar (primary) → OpenAlex (fallback for citations/references).

**Example:**

```bash
axm-bib graph 10.1145/363235.363259 --direction citations -n 10
```

---

## `pdf` — Download, Extract & Organize Paper

```
axm-bib pdf [OPTIONS] REF
```

| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `REF` | | string | *required* | Any identifier (DOI, arXiv ID, HAL ID, etc.) |
| `--output-dir` | `-o` | path | `~/axm/papers/` | Output directory |

Downloads the open-access PDF via multi-source URL chain, extracts Markdown + figures, and writes `paper.bib`.

**URL priority:**

1. S2 Open Access PDF
2. arXiv direct (`arxiv.org/pdf/{id}`)
3. Unpaywall OA locations
4. DOI-based fallbacks (arXiv, ACL Anthology)

**Output structure:**

```
~/axm/papers/{key}/
├── {key}.pdf       # downloaded PDF
├── paper.bib       # BibTeX entry
├── content.md      # extracted Markdown
└── figures/
    ├── fig_001.png
    └── ...
```

**Examples:**

```bash
axm-bib pdf 10.48550/arXiv.1706.03762
axm-bib pdf arXiv:2503.18813
```

```
Downloaded: ~/axm/papers/vaswani2017attention
  PDF: vaswani2017attention.pdf (1,234,567 bytes)
  BibTeX: paper.bib
  Markdown: content.md (8,432 words, 45,123 chars, 12 pages)
  Figures: 8
```

---

## `extract` — Extract Local PDF

```
axm-bib extract [OPTIONS] PDF_PATH
```

| Option | Short | Type | Default | Description |
|---|---|---|---|---|
| `PDF_PATH` | | path | *required* | Path to PDF file |
| `--output-dir` | `-o` | path | auto | Output directory |
| `--figures/--no-figures` | | bool | `True` | Extract figures as PNG |

Extracts Markdown + figures from a local PDF without downloading anything.

**Example:**

```bash
axm-bib extract paper.pdf -o ~/extracted/
```

```
Extracted: ~/extracted/
  Markdown: content.md (6,200 words, 32,000 chars)
  Pages: 8
  Figures: 3
```
