wd-cli

wd-cli is a TypeScript command-line client for exploring and querying Wikidata.

• Search items and properties
• Resolve names to likely entities
• Build curated profiles for company/person/place
• Inspect statements and statement values
• Traverse instance/subclass hierarchies
• Execute SPARQL queries
• Use plain-text output by default or --json for automation

Parity note: command coverage tracks the original Wikidata MCP implementations as a reference baseline: zzaebok/mcp-wikidata and philippesaade-wmde/WikidataMCP.

Quick Start

Run without installing (npx)

npx -y @osolmaz/wd-cli --help
npx -y @osolmaz/wd-cli search-items "Douglas Adams"

Install globally with npm

npm install -g @osolmaz/wd-cli
wd-cli --help

Build from source

git clone https://github.com/osolmaz/wd-cli.git
cd wd-cli
npm ci
npm run build
node dist/cli.js --help

Commands

A practical default flow is:

resolve -> profile -> statements/hierarchy/sparql

• resolve <query> Start from plain text (for example, a person or organization name) and get likely Wikidata entity matches with confidence hints.

• profile <entity-id> (--type company|person|place) Get a concise, curated summary for an entity instead of raw claim dumps. Best when you already have a QID and want a quick answer.

• search-items <query> Find Wikidata items (QIDs) by keyword/vector search. Useful when you want broader discovery results than resolve.

• search-properties <query> Find Wikidata properties (PIDs) such as occupation, country, or official website before querying specific statements.

• get-statements <entity-id> Return direct statements for an entity in text form. Use this when you want a wide fact overview for one QID.

• get-statement-values <entity-id> <property-id> Inspect one property deeply, including ranks, qualifiers, and references. Use this when detail and provenance matter.

• get-instance-and-subclass-hierarchy <entity-id> Walk instance of and subclass of relationships from a starting entity. Useful for classification and context.

• execute-sparql [query] Run custom SPARQL against Wikidata Query Service for advanced filters and graph patterns.

Usage Examples

General examples:

wd-cli resolve "Marie Curie"
wd-cli profile Q7186 --type person
wd-cli search-items "Douglas Adams"
wd-cli search-properties "occupation"
wd-cli get-statements Q42
wd-cli get-statement-values Q42 P106
wd-cli get-instance-and-subclass-hierarchy Q42 --max-depth 2
wd-cli execute-sparql 'SELECT ?human WHERE { ?human wdt:P31 wd:Q5 } LIMIT 2'

Entity-first workflow:

wd-cli resolve "Marie Curie" --limit 5
wd-cli profile Q7186 --type person
wd-cli get-statement-values Q7186 P27

JSON mode:

wd-cli --json search-items "Douglas Adams"
wd-cli --json resolve "Marie Curie"
wd-cli --json profile Q7186 --type person

Equivalent one-shot usage with no install:

npx -y @osolmaz/wd-cli --json search-items "Douglas Adams"

Agent Skill (skillflag)

wd-cli bundles a wikidata agent skill under skills/wikidata.

The skill includes an entity-first workflow for common tasks:

• resolve ambiguous names to candidate QIDs
• build concise company/person/place profiles
• drill into statements, hierarchy, or SPARQL only when needed

List bundled skills:

wd-cli --skill list

Inspect the skill:

wd-cli --skill show wikidata

Install it into your coding agent (example: Codex repo scope):

wd-cli --skill export wikidata | npx skillflag install --agent codex --scope repo

Environment Variables

• WD_API_URI (default https://www.wikidata.org/w/api.php)
• WD_QUERY_URI (default https://query.wikidata.org/sparql)
• TEXTIFER_URI or TEXTIFIER_URI (default https://wd-textify.wmcloud.org)
• VECTOR_SEARCH_URI (default https://wd-vectordb.wmcloud.org)
• WD_VECTORDB_API_SECRET (optional)
• USER_AGENT (recommended to set a descriptive value)
• REQUEST_TIMEOUT_SECONDS (default 15)
• WD_CLI_VERSION (optional version override for version command)
• WD_CLI_COMMIT (optional commit override for version command)
• WD_CLI_DATE (optional date override for version command)

Operational docs

• Usage guide
• Configuration guide
• Troubleshooting guide
• Release guide

License

MIT