OpenAlex Skill

openalex is a human-friendly and agent-friendly CLI for the OpenAlex API. It is designed for fast literature lookup, citation tracing, author/institution discovery, and field projection without forcing users into raw JSON by default.

Install in 10 Seconds

Choose the path that matches your environment:

• skill-aware agents: install the repo skill with npx skills add
• local shell or plain CLI use: install the npm package and run openalex

For skill-aware agents

Install the openalex skill from this repository:

npx skills add shiquda/openalex-skill --skill openalex

Then you can ask your agent to finish the setup steps according to the guide inside the skill, including CLI installation and API key configuration, or you can run those steps yourself with the instructions below.

For local shell or plain CLI use

If your environment does not support repo-distributed skills yet, install the CLI directly:

npm install -g openalex-skill
openalex --help

Why Use It

• human-readable output by default
• targeted extraction with --field
• server-side narrowing with --select when OpenAlex supports it
• works, authors, sources, institutions, topics, publishers, funders, and concepts
• helper flows for related, cited-by, and references
• built-in single-work full-text download when OpenAlex exposes a direct file URL

Quick Start

npm install -g openalex-skill
openalex --help
openalex --version
openalex works search "llm agents" --per-page 5
openalex works get https://doi.org/10.1038/nature12373
openalex works download https://doi.org/10.1038/nature12373

Optional but recommended for higher quotas:

openalex config set api-key your_key_here
openalex config show

Core Examples

Search papers:

openalex works search "retrieval augmented generation" --per-page 5

Get a work by DOI or OpenAlex ID:

openalex works get https://doi.org/10.1038/nature12373
openalex works get W2741809807

Download the best available direct full-text file for one work:

openalex works download https://doi.org/10.1038/nature12373
openalex works download W2741809807 --output ./nature12373.pdf

Trace citations:

openalex works cited-by https://doi.org/10.1038/nature12373 --per-page 5
openalex works references W2741809807 --per-page 5
openalex works related W2741809807 --per-page 5

Find authors and their works:

openalex authors search "Geoffrey Hinton" --per-page 3
openalex authors get https://orcid.org/0000-0002-3141-5845
openalex works list --filter author.id:A5070829652 --per-page 5

Group and analyze:

openalex works group --by publication_year --filter author.id:A5070829652
openalex rate-limit

Output Model

Default output is summary, which is optimized for both humans and agents.

Available formats:

• summary - concise, readable, high-signal output
• detail - readable structured output without transport noise
• json - full structured payload
• jsonl - one JSON object per line
• markdown - heading plus JSON block

In summary, entity rows keep the human-readable title on the first line and include reusable identifiers such as OpenAlex IDs on the secondary line when available.

Quick examples:

openalex works search "crispr" --per-page 3
openalex --format detail works get W2741809807

Field Control

Use --field for client-side projection after the response arrives:

openalex works fields
openalex works get W2741809807 \
  --format detail \
  --field title \
  --field abstract \
  --field authorships.author.display_name

Use --select for server-side field selection when OpenAlex supports it:

openalex works search "crispr" \
  --select id \
  --select title \
  --select cited_by_count

Important --select caveats:

• OpenAlex only supports selecting root-level fields
• group and autocomplete do not support --select
• abstract and abstract_inverted_index are not selectable upstream
• if you need abstract text, prefer --field abstract and avoid --select for that request

Configuration

• OPENALEX_API_KEY - recommended for search and higher-volume use
• OPENALEX_BASE_URL - defaults to https://api.openalex.org
• OPENALEX_MAILTO - optional contact email

Example:

export OPENALEX_API_KEY=your_key_here
openalex works search "graph neural networks" --per-page 5

openalex can also store user-level settings in ~/.openalex-skill/config.json.

Priority order:

• environment variables override stored config
• stored config overrides built-in defaults

Useful commands:

openalex config
openalex config show
openalex config path
openalex config set api-key your_key_here
openalex config unset api-key

Skills

This repository also includes an installable skill definition under skills/openalex/. Skill-specific operational guidance lives in skills/openalex/SKILL.md.

Development

npm install
npm run build
npm exec --package=. openalex -- --help
npm test
npm run typecheck
npm run pack:dry-run

Useful Links

Official OpenAlex resources:

• API docs: https://docs.openalex.org
• LLM quick reference: https://docs.openalex.org/api-guide-for-llms
• Official bulk-download CLI: https://github.com/ourresearch/openalex-official
• API key signup: https://openalex.org/settings/api

Use openalex-official for large bulk-download workflows. Use openalex for interactive querying, lookup, single-work download, citation tracing, grouping, and field projection.