# union-search-skill: one CLI for searching thirty platforms at once

> Union Search Skill is a Python command line tool that fans a single query out to developer sites, social platforms, general search engines and image sources, with one output format. Its own install note warns of a 50MB package limit, and the last push was on 2026-04-14.

**runningZ1/union-search-skill** — 统一搜索工具集 - 跨平台内容搜索解决方案，支持 B 站/抖音/小红书/GitHub/Twitter 等 20+ 平台

- Repository: https://github.com/runningZ1/union-search-skill
- Stars: 761 · Forks: 68
- Language: Python
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/runningz1-union-search-skill

## A single search command across developer, social and general engines

Union Search Skill is a Python toolset that puts one command in front of a very wide set of search back ends. The project describes itself as a unified multi platform search solution, and the command surface is genuinely narrow: `search` runs a multi platform aggregated search, `platform <name>` or a direct platform command such as `google` runs a single engine, `image` handles image search, `download` wraps yt-dlp, `list` prints the available platforms and groups, and `doctor` runs a health check.

The platforms cover three worlds. Developer oriented engines include GitHub, Reddit and Zhihu. Social and video sources include Xiaohongshu, Douyin, Bilibili, Twitter / X, YouTube, Toutiao and Weibo. General search engines range from Google and Bing to keyless options such as DuckDuckGo, Brave, Yahoo, Yandex, Startpage, Ecosia, Qwant and Wolfram Alpha, plus several Chinese entry points. AI driven search adds Tavily, Metaso, Volcengine and Jina, and content subscriptions add RSS and Xiaoyuzhou FM.

The audience is anyone who currently juggles several engine specific clients, and the argument is a coverage argument rather than a quality argument. The project's own comparison table claims more platforms and multiple fallback channels than other open source tools, and it lists image search on eighteen platforms. Those are the maintainers' claims, and the interesting part for a reader is the mechanism behind them.

## Groups, explicit platform lists and the limit flag

A query can be routed three ways. The `--group` option selects a named set of platforms, so a developer oriented request and a social media request use different back ends. The `--platforms` option names platforms explicitly, which is the deterministic path when a result set has to be reproducible. Running a platform directly, for example `google` as a subcommand, is the third path and uses one engine only.

Result volume is controlled separately. The `--limit` flag sets the number of results per platform and overrides the preset, with `--limit 0` meaning no limit. Presets exist for the common cases: `small` returns three results, `medium` returns five and is the default, `large` returns ten and `extra` returns twenty. The same two settings can be pinned in the environment file, where the project documents entries named SEARCH_DEFAULT_LIMIT and SEARCH_LIMIT_PRESET.

The `medium` preset as the default is a deliberate choice with a cost. Five results per platform across a group of ten engines can be a lot of text for a model to read, which is why the `small` preset is described as a way to save tokens. The `--output` option writes results to a file and `--pretty` formats the JSON, while `--format` selects `json`, `markdown` or `text` and `--env-file` points at a different variable file.

## Installing with pip, npm and a copied variable template

The documented install path is a clone of the repository followed by two dependency steps, one for Python and one for Node.js, the latter serving the defuddle and wechat modules.

```bash
pip install -r requirements.txt
```

```bash
npm install
```

The Python requirements are the usual set for a scraping and aggregation tool: `requests`, `python-dotenv`, `lxml`, `pyimagedl`, `yt-dlp`, `tavily-python`, `loguru`, `pydantic>=2.0.0` and `firecrawl-py`. The JavaScript side is small, with `cheerio`, `commander` and `jsdom` declared in `package.json`.

Configuration starts by copying a template, which is then edited with the keys you actually have.

```bash
cp ENV_TEMPLATE.txt .env
```

The first search then looks like this, with the developer group and a small result count:

```bash
python union_search_cli.py search "AI Agent" --group dev --limit 3 --pretty
```

And a single engine can be called on its own:

```bash
python union_search_cli.py google "Python tutorial" --limit 5
```

The `doctor` command is the piece to run first in practice, since it checks for missing dependencies and prints installation guidance. The repository also ships `SKILL.md` and `_meta.json` at the top level, which marks it as a skill package for a coding agent harness rather than only a plain script.

## Which engines work depends on the keys in your environment file

The platform tables separate engines that need credentials from those that do not, and this distinction decides how much of the tool actually functions. Google needs an API key and a search engine id, Tavily needs a key, SerpAPI supplies Bing, YouTube needs a Data API key, and Metaso and Volcengine each need their own. GitHub search is configured with a token, and the TikHub token covers Xiaohongshu, Douyin, Bilibili and Twitter.

```bash
GITHUB_TOKEN=your_github_token_here
TIKHUB_TOKEN=your_tikhub_token_here
GOOGLE_API_KEY=your_google_api_key_here
TAVILY_API_KEY=tvly-your_tavily_api_key_here
```

The keyless half of the catalogue, DuckDuckGo, Brave, Yahoo, Bing, Wikipedia and Anna's Archive, is reached through optional proxy settings, and several of those engines are described in the project documentation as returning unstable results because they are not API backed.

Two entries deserve caution. Weibo is marked as requiring a cookie, and the variable template carries a `WEIBO_COOKIE` field alongside a filter, a date window and a limit, which means authenticating as a logged in user to query it. Zhihu is configured with a cookie too. Cookies are personal credentials, and putting one in a shared `.env` is a different decision from adding an API key, especially for a tool that is distributed as a skill package.

The `.env.example` file also shows that the Baidu integration accepts two variable names, with the newer `BAIDU_API_KEY` preferred and the older `BAIDU_QIANFAN_API_KEY` still accepted, and that SerpAPI supports two keys for rotation and failover.

## Content extraction falls through Jina, Firecrawl and Defuddle

Turning a URL into readable text is a separate capability from search, and the project handles it with a three stage fallback. The documentation states the order plainly: Jina Reader is tried first, Firecrawl is attempted when that fails, and the local Defuddle engine is the last resort, which is described as the way to keep extraction success high when the hosted services fail.

That chain is the most useful single idea in the design. Search back ends break for all sorts of reasons, quotas, blocking, changed markup, and a three engine chain means a page that one service refuses can still be read by the next. The same instinct appears elsewhere in the tool, where a SerpAPI key can be a second Bing source and where a keyless engine sits beside a keyed one.

The cost of the chain is latency and unpredictability, because the caller cannot tell in advance which engine produced the text. The README publishes its own measurement run from 2026-03-05 for a search across twelve engines, reporting 12 of 12 successful platforms, 11.14 seconds in total, 91 results and an average of 7.6 results per platform, with Metaso listed as the fastest at 1.00 second and Volcengine the slowest at 6.45 seconds. That is the project's own test data on its own machine, not a guarantee about your environment, and it comes from a run several months before the last commit.

## The 50MB package limit and an install note pointing elsewhere

The install section carries a warning that is unusual enough to be worth reading carefully. The project files are large, around 100MB or more, and the Claude Code Core Hub imposes a 50MB size limit on skills and agents, so a version installed through the Core Hub is missing files because large ones are ignored. The recommendation is to download the full version from the repository directly.

That recommendation links to https://github.com/anyangrc/union-search-skill, which is a different owner path from the repository this article describes, runningZ1/union-search-skill. The two are not obviously the same place, and the documentation does not explain the relationship. Anyone who follows the link literally will end up somewhere other than where they cloned, which is the kind of detail that deserves a check before a tool is wired into an automated pipeline.

There is a second limitation hiding in the same place. The roadmap marks a multi platform download tool for Douyin video, Xiaohongshu posts, Bilibili video and YouTube video as in development, and it lists channel auto switching on failure, result caching and additional search channels as planned rather than shipped. The feature list above those entries also claims automatic degradation when a primary channel fails, while the roadmap still lists that capability as planned, so the two parts of the documentation do not fully agree about what the fallback layer does today.

## A last push in April, no releases, and a licence field GitHub cannot read

The repository is not archived, but the commit record is old: the last push was on 2026-04-14, and there are no GitHub releases, so there is no versioned distribution history to point at. The code therefore sits in a state where the documentation describes features that the roadmap also lists as upcoming, and where an important dependency list, an environment template and a CLI surface can all change without a release note.

The licence is similarly ambiguous. The README carries an MIT badge, and the project's own licence section points to a licence file, but GitHub does not classify the licence field for this repository, so anyone depending on it has to read the licence text directly rather than trust a badge.

The top level tree gives a sense of the shape: `union_search_cli.py` and `uniarch.py` at the root, with `config/`, `scripts/`, `references/`, `requirements.txt`, `package.json`, `ENV_TEMPLATE.txt` and `.env.example` beside them. The `references/` and `config/` directories are where platform definitions and groups presumably live, and `_meta.json` and `SKILL.md` are what make the package loadable as a skill. With a 2026-04-14 last push, none of that has changed in over half a year.

## Where a single engine client differs from an aggregator

The obvious alternative is to call one engine's API directly from a script, or to use a client library for that one engine. The difference in approach is not a difference in result quality but in what the caller has to maintain. A direct client needs one credential and one response parser, and it fails when that one endpoint is blocked or its quota is spent. The aggregator accepts that failure by trying the next channel, at the cost of a much larger configuration surface, a larger dependency set including a JavaScript runtime, and a slower worst case.

The other alternative is a general purpose search tool that asks the model to browse. That approach returns prose rather than structured records, so it is not a substitute when the output has to be parsed field by field, for example to collect download candidates across platforms. The `search` command in this project can export those candidates to a JSON file, which is the piece that makes the tool usable in a pipeline rather than only in a conversation.

For a one off question, a direct engine call is simpler and cheaper. For repeated cross platform collection, the aggregator earns its extra configuration, provided you accept the cookies, keys and proxies it expects and the fact that the last commit is from April 2026.

## Conclusion

Union Search Skill fits a researcher or agent that needs one query to reach many platforms and one JSON output to parse, and it suits teams willing to hold API keys for Google, Tavily, SerpAPI and the Chinese platforms. It is the wrong tool if you need a single authoritative source, or if you cannot accept a project whose last push was on 2026-04-14, whose install note points to a repository under a different owner, and whose GitHub licence field is not classified. Before adopting it, run `python union_search_cli.py doctor`, decide whether the Weibo cookie in `.env` is acceptable in your environment, and confirm the download link in the install note matches the repository you cloned.

## FAQ

### How do I install and run the Union Search Skill CLI?

Install the Python dependencies with `pip install -r requirements.txt` and the Node.js ones with `npm install`, then copy the environment template with `cp ENV_TEMPLATE.txt .env` and fill in the keys you need. Run `python union_search_cli.py doctor` to check for missing dependencies before the first query.

### Which Union Search Skill platforms need API keys?

Google, Tavily, SerpAPI, YouTube, Metaso, Volcengine, GitHub and the TikHub backed social platforms all read credentials from the `.env` file. DuckDuckGo, Brave, Yahoo, Bing, Wikipedia and Anna's Archive are reached through optional proxy settings instead.

### How many results does a Union Search Skill search return?

The `--limit` flag sets results per platform and overrides the preset, with `--limit 0` returning everything. Presets are `small` for three, `medium` for five as the default, `large` for ten and `extra` for twenty, and `SEARCH_DEFAULT_LIMIT` and `SEARCH_LIMIT_PRESET` in the environment file set the defaults.

### Does the Union Search Skill project support downloading videos?

The CLI exposes a `download` command based on yt-dlp, and the requirements include yt-dlp. The roadmap also lists a broader multi platform download tool covering Douyin, Xiaohongshu, Bilibili and YouTube as still in development.

### Why does the Union Search Skill install note recommend downloading from GitHub?

The project files run to roughly 100MB or more, and the Claude Code Core Hub limits skills and agents to 50MB, so a Core Hub install silently drops large files. The note therefore recommends fetching the complete version from the repository directly, and it links to a repository under the owner anyangrc rather than runningZ1.

## Sources

- [Issues](https://github.com/runningZ1/union-search-skill/issues)
- [README](https://github.com/runningZ1/union-search-skill/blob/master/README.md)
- [runningZ1/union-search-skill on GitHub](https://github.com/runningZ1/union-search-skill)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/runningz1-union-search-skill