axq

README

axq

A small CLI for downloading and organizing arXiv PDFs, modeled on ghq.

axq get <arxiv-id> fetches the PDF and a metadata sidecar into a tidy directory tree. axq list, axq show, axq rm operate on that tree the way ghq's commands operate on cloned repos.

Install

go install github.com/stheno2010/axq@latest

Or build from source:

git clone <this-repo> && cd axq && go build -o axq .

Quick start

# fetch a paper (PDF + metadata)
$ axq get 1706.03762
fetch 1706.03762 -> /home/you/axq/arxiv.org/1706/1706.03762
/home/you/axq/arxiv.org/1706/1706.03762

# accepts URLs and old-style IDs too
$ axq get https://arxiv.org/abs/2401.12345
$ axq get cs/0701001

# show metadata
$ axq show 1706.03762
ID:         1706.03762v7
Title:      Attention Is All You Need
Authors:    Ashish Vaswani, Noam Shazeer, ...
Categories: cs.CL, cs.LG
Published:  2017-06-12
Updated:    2023-08-02
Path:       /home/you/axq/arxiv.org/1706/1706.03762

# list everything you've downloaded
$ axq list
arxiv.org/1706/1706.03762
arxiv.org/2401/2401.12345

# search by title / category / author
$ axq list attention
$ axq list --category cs.CL
$ axq list --author "Vaswani"

# bulk download from a file
$ cat reading-list.txt | axq get -P

# update to the latest version
$ axq get -u 1706.03762

# remove
$ axq rm 1706.03762

Commands

Command	Description
axq get <id>...	Download PDF and metadata. -u updates if a newer version exists. -P parallelizes (max 6). With no args, reads IDs from stdin.
axq list [query]	List downloaded papers. Filters: -e exact, -p full path, --unique last path component only, --category, --author.
axq show <id>	Print metadata for a paper.
axq rm <id>	Remove a paper directory. --dry-run to preview.
axq root	Print the configured root directory. --all shows every configured root.
axq migrate <pdf-or-dir>	Move existing PDFs into the axq tree, extracting the arXiv ID from filenames. -y skips confirmation, --dry-run previews.

Configuration

axq picks its root directory in this order:

1. $AXQ_ROOT environment variable.
2. git config --get-all axq.root — multiple values are allowed; the last one wins for new downloads.
3. Default: ~/axq.

# example
git config --global axq.root "$HOME/papers"

Path layout

$AXQ_ROOT/
└── arxiv.org/
    ├── 2401/
    │   └── 2401.12345/
    │       ├── paper.pdf
    │       └── .axq-meta.json
    └── 1706/
        └── 1706.03762/
            ├── paper.pdf
            └── .axq-meta.json

Old-style IDs (cs/0701001, hep-th/9901001) live under arxiv.org/<archive>/<yymm>/<archive>-<num>/.

The .axq-meta.json sidecar records id, version, title, authors, categories, abstract, and timestamps. It also serves as the marker file axq list looks for when walking the tree.

arXiv API politeness

axq throttles outbound requests to roughly one every 3 seconds, matching arXiv's published rate-limit guidelines. This applies to both metadata and PDF fetches; parallel get -P requests are serialized through the same limiter.

License

MIT — see LICENSE.

Differences from ghq

• No VCS abstraction — everything is HTTP.
• No create (you can't git init a paper).
• No --shallow / --bare / --branch flags.
• arXiv-specific additions: metadata sidecar, version-aware -u, show command, --category / --author filters.