The OpenAlex API provides access to a comprehensive catalog of scholarly works, authors, sources, institutions, topics, keywords, publishers, and funders. OpenAlex indexes over 250 million scholarly works.
Learn more at Openalex.
Printed by @hiten-shah (Hiten Shah).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export OPENALEX_API_KEY="<paste-your-key>"
You can also persist this in your config file at ~/.config/openalex-pp-cli/config.toml.
3. Verify Setup
openalex-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
openalex-pp-cli authors list
Unique Features
These capabilities aren't available in any other tool for this API.
Research graph retrieval
works list — Search scholarly works with compact JSON, field selection, filters, sorting, and live API fallback.authors list — Search authors and retrieve canonical OpenAlex author records for citation and collaborator research.institutions list — Search institutions with country/type metadata for affiliation and ecosystem analysis.sources list — Search journals, repositories, and venues with compact agent-oriented output.topics list — Explore OpenAlex topics for research-area discovery and downstream filtering.
Usage
Run openalex-pp-cli --help for the full command reference and flag list.
Commands
authors
People who create scholarly works
openalex-pp-cli authors get - Retrieve a single author by OpenAlex ID or ORCID.openalex-pp-cli authors list - Get a list of authors with optional filtering, searching, sorting, and pagination.
autocomplete
Fast typeahead search for any entity type
openalex-pp-cli autocomplete autocomplete - Fast typeahead search returning up to 10 results. Use for search-as-you-type interfaces.
awards
Research grants and funding awards
openalex-pp-cli awards get - Retrieve a single award by its OpenAlex ID.openalex-pp-cli awards list - Get a list of research grants and funding awards.
changefiles
Manage changefiles
openalex-pp-cli changefiles get - Get details for a specific date's changefile, including which entity types changed, how many records, and download links in JSONL and Parquet formats. For a full guide on using changefiles to keep your local data current, see Download Changefiles. Requires a paid plan — contact sales@openalex.org or see pricing.openalex-pp-cli changefiles list - List all available changefile dates. Each date has downloadable files containing every entity record that was created or modified on that day. For a full guide on using changefiles to keep your local data current, see Download Changefiles. Requires a paid plan — contact sales@openalex.org or see pricing.
concepts
Legacy taxonomy of research areas (deprecated - use Topics instead)
openalex-pp-cli concepts get - DEPRECATED: Use Topics instead. Retrieve a single concept by OpenAlex ID.openalex-pp-cli concepts list - DEPRECATED: Use Topics instead. Get a list of concepts from the legacy taxonomy.
continents
Geographic continents (7 total)
openalex-pp-cli continents get - Retrieve a single continent by its Wikidata Q-ID.openalex-pp-cli continents list - Get a list of continents (7 total).
countries
Geographic countries for filtering research by location
openalex-pp-cli countries get-country - Retrieve a single country by its ISO 3166-1 alpha-2 code.openalex-pp-cli countries list - Get a list of countries. Useful for filtering works by author affiliation country.
domains
Top-level categories in the topic hierarchy (4 total)
openalex-pp-cli domains get - Retrieve a single domain by its ID (1-4).openalex-pp-cli domains list - Get a list of domains (top-level topic categories). There are only 4 domains: Life Sciences, Social Sciences, Physical Sciences, and Health Sciences.
fields
Second-level categories in the topic hierarchy (26 total)
openalex-pp-cli fields get - Retrieve a single field by its ID.openalex-pp-cli fields list - Get a list of fields (second-level topic categories). There are 26 fields spread across 4 domains.
funders
Organizations that fund research
openalex-pp-cli funders get - Retrieve a single funder by OpenAlex ID or Crossref Funder ID.openalex-pp-cli funders list - Get a list of funders with optional filtering, searching, sorting, and pagination.
institution-types
Types of institutions (education, healthcare, company, etc.)
openalex-pp-cli institution-types list - Get a list of institution types (education, healthcare, company, etc.).
institutions
Universities, research organizations, and other affiliations
openalex-pp-cli institutions get - Retrieve a single institution by OpenAlex ID or ROR.openalex-pp-cli institutions list - Get a list of institutions with optional filtering, searching, sorting, and pagination.
keywords
Short phrases identified from works' topics
openalex-pp-cli keywords get - Retrieve a single keyword by OpenAlex ID.openalex-pp-cli keywords list - Get a list of keywords with optional filtering, searching, sorting, and pagination.
languages
Languages of scholarly works
openalex-pp-cli languages get - Retrieve a single language by its ISO 639-1 code.openalex-pp-cli languages list - Get a list of languages used in scholarly works.
licenses
Open access licenses (CC BY, CC BY-SA, etc.)
openalex-pp-cli licenses list - Get a list of open access licenses (CC BY, CC BY-SA, etc.).
publishers
Companies and organizations that publish scholarly works
openalex-pp-cli publishers get - Retrieve a single publisher by OpenAlex ID.openalex-pp-cli publishers list - Get a list of publishers with optional filtering, searching, sorting, and pagination.
rate-limit
Manage rate limit
openalex-pp-cli rate-limit get - Check your current rate limit status including usage and remaining allowance.
sdgs
UN Sustainable Development Goals (17 total)
openalex-pp-cli sdgs get - Retrieve a single Sustainable Development Goal by its ID (1-17).openalex-pp-cli sdgs list - Get a list of UN Sustainable Development Goals. There are 17 SDGs.
source-types
Types of sources (journal, repository, conference, etc.)
openalex-pp-cli source-types list - Get a list of source types (journal, repository, conference, etc.).
sources
Journals, repositories, and other venues where works are hosted
openalex-pp-cli sources get - Retrieve a single source by OpenAlex ID or ISSN.openalex-pp-cli sources list - Get a list of sources (journals, repositories, conferences) with optional filtering, searching, sorting, and pagination.
subfields
Third-level categories in the topic hierarchy (254 total)
openalex-pp-cli subfields get - Retrieve a single subfield by its ID.openalex-pp-cli subfields list - Get a list of subfields (third-level topic categories). There are 254 subfields spread across 26 fields.
text
Manage text
openalex-pp-cli text classify - DEPRECATED: This endpoint is deprecated and not recommended for new projects. It will not receive updates or support.
Classify arbitrary text to find relevant OpenAlex topics. Costs $0.01 per request.
topics
Research topics automatically assigned to works
openalex-pp-cli topics get - Retrieve a single topic by OpenAlex ID.openalex-pp-cli topics list - Get a list of topics with optional filtering, searching, sorting, and pagination. Topics are research areas automatically assigned to works.
work-types
Types of scholarly works (article, book, dataset, etc.)
openalex-pp-cli work-types list - Get a list of work types (article, book, dataset, etc.).
works
Scholarly documents like journal articles, books, datasets, and theses
openalex-pp-cli works get - Retrieve a single work by its OpenAlex ID or external ID (DOI, PMID, PMCID, MAG ID). External IDs can be passed as full URLs or URN format (e.g., doi:10.1234/example or pmid:12345678).openalex-pp-cli works list - Get a list of scholarly works with optional filtering, searching, sorting, and pagination. Works include journal articles, books, datasets, theses, and more.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
openalex-pp-cli authors list
# JSON for scripting and agents
openalex-pp-cli authors list --json
# Filter to specific fields
openalex-pp-cli authors list --json --select id,name,status
# Dry run — show the request without sending
openalex-pp-cli authors list --dry-run
# Agent mode — JSON + compact + no prompts in one flag
openalex-pp-cli authors list --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
openalex-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/openalex-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
OPENALEX_API_KEY | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
openalex-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $OPENALEX_API_KEY
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press