arx

arx is a fast, minimal, script-friendly CLI for researching papers on arXiv. It presents concise tables to humans and predictable JSON or JSONL to agents.

This is a CLI-only project. Its Go packages are internal implementation details; the supported interface is the arx command.

Highlights

• Natural-language search plus title, author, abstract, category, and date filters
• Advanced raw arXiv queries and deterministic sorting/pagination
• Paper lookup by ID, abstract URL, or PDF URL
• Human-readable tables and full paper details
• Stable JSON envelopes, JSONL streaming, and paper-field projection
• Clean stdout, structured stderr errors, and documented exit codes
• Cross-process rate limiting and bounded retries for transient failures
• No authentication, API key, configuration file, or interactive prompt required

Install

Install from source with Go 1.24 or newer:

go install github.com/mathisarends/arxcli/cmd/arx@latest

Or build from a checkout:

make build
./bin/arx --help

On Windows without make:

go build -trimpath -o bin/arx.exe ./cmd/arx

Release archives for Windows, Linux, and macOS are produced by GoReleaser when a version tag is published.

Search

Start with ordinary words. By default each word must occur somewhere in the paper metadata:

arx search "retrieval augmented generation"
arx search "reasoning agents" --category cs.AI,cs.CL --from 2025-01-01
arx search --author "Yann LeCun" --title "deep learning" --limit 25
arx search --category cs.LG --exclude-category cs.CV --sort submitted --order desc

Use --exact to treat the positional query as one phrase. Structured text filters are phrases and can be repeated. Multiple included categories are ORed; all other positive filters are ANDed.

For the complete arXiv query language, pass --raw:

arx search --raw 'au:del_maestro AND (ti:checkerboard OR ti:pyrochlore)'
arx search --raw 'jr:Nature ANDNOT cat:quant-ph' --from 2020-01-01

Use --start with the returned next_start to page. One call may request up to 2,000 entries, though focused queries and smaller pages are kinder to arXiv. Category identifiers are listed in the official category taxonomy.

Get paper metadata

arx get 1706.03762
arx get https://arxiv.org/abs/1706.03762 https://arxiv.org/pdf/2005.14165.pdf

The output includes the abstract, authors, dates, categories, DOI and journal reference when present, plus canonical HTTPS abstract and PDF links.

Agent and scripting contract

--json emits one document with papers and meta. --fields implies JSON and projects every paper to the requested fields:

arx --json search "tool using agents" --category cs.AI --limit 5
arx --fields=id,title,authors,published,pdf_url --compact search "small language models"
arx --jsonl --fields=id,title,summary search "test time compute" --limit 100

Example envelope:

{
  "meta": {
    "items_per_page": 2,
    "next_start": 2,
    "query": "all:tool AND all:using AND all:agents AND cat:cs.AI",
    "start": 0,
    "total_results": 123
  },
  "papers": [
    {
      "id": "2501.01234v1",
      "title": "Example",
      "authors": ["A. Researcher"]
    }
  ]
}

• stdout contains only result data.
• Errors and human-only notices go to stderr.
• --jsonl writes exactly one compact paper object per line, without metadata.
• JSON errors use { "error": { "code", "message", "hint", "status" } }.
• Misspelled --fields fail before any result data is written.
• The CLI never prompts, so unattended agent calls cannot hang on input.

See docs/cli.md for the complete query, output, rate-limiting, and exit-code contract.

Flags

Global flags apply to every command and must be placed before the command name.

Flag	Applies to	Description	Default
--json	any	Emit stable JSON on stdout.	off
--jsonl	search, get	Emit one compact JSON paper per line.	off
--fields=FIELD,...	search, get	Project papers to these fields; implies JSON.	all fields
--compact	any	Emit compact rather than indented JSON.	off
--timeout	any (network)	HTTP request timeout.	30s
--max-attempts	any (network)	Maximum attempts for rate limits and transient failures.	3

search accepts these flags in addition to the global ones:

Flag	arXiv field	Description	Default
QUERY (positional)	all	Natural-language terms to find across all metadata.	—
--raw=EXPR	—	Advanced arXiv search_query expression; structured filters still apply.	—
--exact	—	Treat the positional query as one exact phrase.	off
--title=PHRASE	ti	Require a title phrase; repeatable.	—
--author=NAME	au	Require an author name; repeatable.	—
--abstract=PHRASE	abs	Require an abstract phrase; repeatable.	—
--category=ID	cat	Include a category (OR); repeat or comma-separate.	—
--exclude-category=ID	cat	Exclude a category; repeat or comma-separate.	—
--from=DATE	submittedDate	Earliest submission date, inclusive (YYYY-MM-DD).	—
--to=DATE	submittedDate	Latest submission date, inclusive (YYYY-MM-DD).	—
--sort	—	Result ordering: relevance, submitted, or updated.	relevance
--order	—	Sort direction: desc or asc.	desc
--limit	—	Number of papers to return (1-2000).	10
--start	—	Zero-based result offset for pagination.	0

get accepts one positional argument in addition to the global flags:

Flag	Description
ID... (positional)	One or more arXiv IDs, abstract URLs, or PDF URLs (up to 100).

A few advanced flags are hidden from --help but documented here and in docs/cli.md:

Flag	Env var	Description
--base-url	ARX_BASE_URL	Override the arXiv API base URL.
--state-dir	ARX_STATE_DIR	Override the rate-limit state directory.
--rate	ARX_RATE_INTERVAL	Override the minimum interval between API requests.

Polite API use

arXiv requires legacy API clients to use one connection and make no more than one request every three seconds. arx enforces this across concurrent local processes using a shared lock held for the full request and a timestamp. It also:

• honors Retry-After and retries HTTP 429/500/502/503/504 responses;
• uses exponential backoff with a bounded number of attempts;
• sends an identifiable user agent and applies a response-size limit.

Every invocation fetches fresh results, including repeated calls with an identical query.

Development

make fmt
make test
make vet
make build

The implementation follows the CLI structure and automation contracts of mathisarends/go-withings.