fandom-cli

name	fandom-cli
description	Query Fandom and other MediaWiki wikis via API. Triggers: fandom, wiki, mediawiki, infobox, search.

Fandom CLI

Query any Fandom wiki (or other MediaWiki-based wiki like Miraheze) via MediaWiki API. Fetches pages, infoboxes, categories, search results, and images.

Preconditions

1. fandom CLI available — try commands in this order:

   ~/.local/bin/fandom --help             # preferred Cohub wrapper
   fandom --help                          # available on PATH
   python -m fandom_cli --help            # module in PYTHONPATH or pip-installed
   python -m fandom_cli.cli --help        # fallback: cd to skill directory first
   

   If none of the above work, install into a sandbox-local venv outside the workspace:

   SKILL_DIR="/workspace/.agents/skills/fandom-cli"
   python3 -m venv ~/venvs/fandom-cli
   PIP_USER=false ~/venvs/fandom-cli/bin/pip install --upgrade pip
   PIP_USER=false ~/venvs/fandom-cli/bin/pip install -e "$SKILL_DIR"
   mkdir -p ~/.local/bin
   ln -sf ~/venvs/fandom-cli/bin/fandom ~/.local/bin/fandom
   export PATH="$HOME/.local/bin:$PATH"
   

   If editable install is unavailable, install dependencies and use PYTHONPATH:

   SKILL_DIR="/workspace/.agents/skills/fandom-cli"
   python3 -m venv ~/venvs/fandom-cli
   PIP_USER=false ~/venvs/fandom-cli/bin/pip install typer httpx beautifulsoup4 markdownify
   mkdir -p ~/.local/bin
   cat > ~/.local/bin/fandom << 'SCRIPT'
   #!/bin/bash
   export PYTHONPATH="/workspace/.agents/skills/fandom-cli:${PYTHONPATH:-}"
   exec "$HOME/venvs/fandom-cli/bin/python" -m fandom_cli.cli "$@"
   SCRIPT
   chmod +x ~/.local/bin/fandom
   export PATH="$HOME/.local/bin:$PATH"
   

2. Internet connectivity — Fandom's api.php endpoint must be reachable
3. Cloudflare fallback configured — set FANDOM_PROXY_URL if you expect blocked requests

Rate Limiting

Hard rule: 1 request per second. The CLI enforces this internally. Do not attempt to bypass or parallelize calls. Fandom's API goodwill depends on responsible use.

Workflow

1. Determine the wiki identifier

Fandom wikis — use the subdomain:

• "Don't Starve Wilson" → dontstarve
• "Harry Potter character" → harrypotter
• "Resident Evil Leon" → residentevil

Non-Fandom MediaWiki wikis (e.g. Miraheze) — use the full hostname:

• "1d6chan D&D" → 1d6chan.miraheze.org
• The CLI auto-detects non-Fandom hosts and uses /w/api.php (standard MediaWiki path)

Full URL base — pass a complete API endpoint:

• https://custom.wiki/api.php

Important: Non-Fandom wikis may be behind Cloudflare. Set FANDOM_PROXY_URL to route requests through a serverless proxy. Without it, Cloudflare-protected wikis will fail with 403. The proxy's /proxy?url= endpoint is used automatically for non-Fandom hosts when Cloudflare is detected.

When unclear, ask the user: "Which wiki? (Fandom subdomain or full hostname)"

2. Select command based on user intent

User intent	Command
Read page content	fandom page <wiki> <title> --format markdown
Get structured data (stats, attributes)	fandom infobox <wiki> <title>
Discover pages by type	fandom category <wiki> <name> --limit N
Search for a topic	fandom search <wiki> <query> --limit N
Get page images	fandom images <wiki> <title> --entity-match --limit N
Get page metadata	fandom metadata <wiki> <title>

Note: If the fandom command is unavailable, try ~/.local/bin/fandom first. If that also fails, install the sandbox-local venv shown above. Do not create or rely on a .venv inside the workspace skill directory.

3. Handle output

• page --format markdown: Return raw markdown to user (best for reading)
• page --format json: Parse JSON, extract html or other fields as needed
• page --format text: Return plain text (most compact)
• infobox: Returns JSON key-value pairs. Present in structured format
• category: Returns list of pages with titles and URLs. Present as bulleted list
• search: Returns ranked results with snippets. Present top matches
• images: Returns image URLs and filenames. Can render markdown images or list URLs
• metadata: Returns pageid, URL, categories. Use for verification or linking

4. Error handling

Error	Cause	Action
"Page not found"	Title doesn't exist	Try search: fandom search <wiki> <partial title>
"No infobox found"	Page lacks portable-infobox	Fall back to fandom page <wiki> <title> --format markdown
Empty category	Category has no direct pages (only subcats)	Try broader category or search
API Error [429]	Rate limited	Wait and retry (CLI auto-retries 3x)
Empty search	No matches	Broaden query or check wiki subdomain

Constraints

• Invocation: Try ~/.local/bin/fandom or fandom first. If unavailable, install the sandbox-local venv before falling back to python -m fandom_cli.
• Always use kebab-case wiki names: dontstarve not Don't Starve
• Quote titles with spaces: fandom page dontstarve "Dark Sword"
• Page titles are case-sensitive in the URL but MediaWiki is usually forgiving
• Special characters: The CLI auto-encodes ' and spaces, but quote the shell argument
• Category prefix optional: fandom category dontstarve Characters works same as Category:Characters
• No concurrent calls: Rate limiter is global per process; do not spawn parallel fandom processes
• Image URLs are CDN links: Validity is not guaranteed long-term; use promptly

Anti-abuse

This tool relies on Fandom's free API. When using it:

• Do not script bulk downloads of 100+ pages
• Do not run multiple instances simultaneously
• Respect the 1 req/s limit (enforced)
• If a wiki blocks API access, stop and notify user

Local cache

Successful API responses are cached on disk for 24 hours by default. Set FANDOM_CACHE_TTL_SECONDS=0 to disable. See README.md for configuration details.

Installation Troubleshooting

"ModuleNotFoundError: No module named 'fandom_cli'"

The module isn't in Python's search path. Fix by installing the skill into a sandbox-local venv:

SKILL_DIR="/workspace/.agents/skills/fandom-cli"
python3 -m venv ~/venvs/fandom-cli
PIP_USER=false ~/venvs/fandom-cli/bin/pip install --upgrade pip
PIP_USER=false ~/venvs/fandom-cli/bin/pip install -e "$SKILL_DIR"
mkdir -p ~/.local/bin
ln -sf ~/venvs/fandom-cli/bin/fandom ~/.local/bin/fandom
export PATH="$HOME/.local/bin:$PATH"

If editable install is unavailable, use the PYTHONPATH wrapper from Preconditions.

"externally-managed-environment"

Do not use system pip. Create ~/venvs/fandom-cli/ and install there with PIP_USER=false, or use the PYTHONPATH wrapper from Preconditions.

Cloudflare Fallback

If fandom-cli hits Cloudflare protection (403), it automatically retries through the serverless proxy configured by FANDOM_PROXY_URL.

• Fandom wikis: uses proxy's /?wikiname=... endpoint
• Non-Fandom wikis (Miraheze, etc.): uses proxy's /proxy?url=... generic endpoint

The same FANDOM_PROXY_URL env var covers both cases — the CLI selects the right proxy format automatically.

See reference/DENO_DEPLOY.md for Deno registration, deployment steps, and proxy code.

If FANDOM_PROXY_URL is missing or unavailable:

1. Check whether the proxy URL is configured correctly
2. Try again later if the request is rate limited or temporarily blocked
3. For simple lookups, suggest visiting the wiki directly
4. For structured data, note that infobox formats vary by wiki and may need manual inspection