CLI 命令手册

IconHash 提供 11 个子命令，覆盖哈希、识别、指纹、服务四大类操作。

记不住命令？

日常 90% 的需求，记住一条就够：iconhash identify <url>。其余命令按需 --help 查阅。

命令全景

全局参数

全局参数表（点击展开）

参数	说明
`-d, --debug`	显示详细调试输出
`--engine <name>`	输出指定搜索引擎格式（fofa/shodan/censys/quake/zoomeye/hunter）
`--uint32`	以无符号 32 位整数输出哈希
`--no-color`	禁用彩色输出
`-h, --help`	查看帮助

全局参数可与任意子命令组合

--engine 与 --uint32 是全局开关，对 url/file/base64/identify/batch 均生效。例如 iconhash file favicon.ico --engine fofa --uint32 一次产出 uint32 的 Fofa 语法。

🔢 哈希计算类

`url` — 从 URL 计算哈希

注意：URL 必须是图标直链

url 接收的是图标文件地址（如 https://x.com/favicon.ico），不是网页地址。若传入网页 URL，会拿到 HTML 的哈希，与搜索引擎对不上。请用 identify 处理网页。

bash

iconhash url https://example.com/favicon.ico

url 完整参数表

参数	说明
`url` (位置参数)	图标直接 URL
`-u, --url`	同上，显式指定
`--engine`	输出搜索语法
`--uint32`	uint32 格式

bash

# Shodan 格式
iconhash url https://example.com/favicon.ico --engine shodan
# → http.favicon.hash:-1161367058

`file` — 从本地文件计算哈希

支持管道与 stdin

file 可读取管道输入，传 - 表示从 stdin 读。常见用法：cat x.ico | iconhash file -，或配合 curl 流式下载：curl -sL https://x.com/favicon.ico | iconhash file - --engine fofa。

bash

iconhash file favicon.ico
iconhash file -f favicon.ico --uint32
# 从管道读取
cat favicon.ico | iconhash file - --engine shodan

`base64` — 从 base64 数据计算哈希

数据需为标准 Base64

base64 期望输入是图标文件的 Base64 编码字符串（即 base64 favicon.ico 的输出），而非图标 URL 或网页源码。若直接传入网页 HTML 的 Base64，得到的哈希将与搜索引擎对不上。

从 Shodan 历史数据复算

Shodan 等引擎的原始结果里常出现 data:image/png;base64,xxxx 字段。把 base64, 后的部分存入文件，再 iconhash base64 encoded.txt 即可复算哈希做指纹匹配。

bash

iconhash base64 encoded.txt
iconhash base64 -b encoded.txt --engine fofa

🔍 识别发现类

`identify` — 一键端到端识别（推荐）推荐

最常用的命令，一条命令完成全部流程：

bash

iconhash identify https://www.example.com
iconhash identify https://www.example.com --engine fofa
iconhash identify -d https://www.example.com   # 调试模式

identify = discover + hash + lookup + format

identify 串联了发现、哈希、指纹匹配、6 引擎语法输出四步。日常绝大多数场景直接用它即可，无需手动分步。需要中间产物（如仅图标 URL）时再退回 discover。

`discover` — 仅发现图标识别

只发现不哈希，返回网站所有图标 URL：

discover vs identify 怎么选

只需列出图标 URL（用于人工核查、批量下载）用 discover；需要哈希 + 指纹 + 搜索语法的完整报告用 identify。identify 内部已包含 discover，无需串联调用。

bash

iconhash discover https://www.example.com

`batch` — 批量处理推荐识别

并发处理大量 URL：

性能建议

-w（worker 数）建议设为 10~20，默认 5 偏保守
大批量优先用 -o csv 流式输出，避免 JSON 全量收集撑爆内存
网络是瓶颈时考虑 --proxy 代理池分流

bash

iconhash batch -f urls.txt -w 10 -o json
cat urls.txt | iconhash batch

batch 完整参数表

参数	说明
`-f, --file`	输入文件
`-i, --input`	同上
`-w, --workers`	并发数（默认 5）
`-o, --output`	输出格式 text/json/csv

📚 指纹管理类

`lookup` — 哈希查指纹指纹

哈希为负数时务必用 -- 分隔

int32 哈希常为负数（如 -1161367058），会被 cobra/pflag 误判为未知 flag。解决：在位置参数前加 -- 终止选项解析，如 iconhash lookup -- -305179312。若用 -i 显式指定则不受影响。

bash

# int32 哈希
iconhash lookup -i -1161367058

# uint32 哈希
iconhash lookup -i 3133600238 --uint32

# 直接传位置参数（负数必须加 --）
iconhash lookup -- -305179312

`fingerprints` — 指纹库操作指纹

Lite 版用户优先 fingerprints update

Lite 构建不内嵌完整指纹库。首次使用前执行 iconhash fingerprints update 从 GitHub 拉取最新指纹并缓存到本地，后续 lookup/identify 才能命中。Full 构建已内嵌，无需更新。

bash

# 列出全部
iconhash fingerprints list

# 搜索
iconhash fingerprints search nginx

# 更新（Lite 版从远程拉取）
iconhash fingerprints update

🖥️ 服务模式类

`server` — HTTP API 服务器服务

生产环境务必设置 --auth-token

默认无认证。暴露在公网时务必加 --auth-token 并通过 Authorization: Bearer <token> 或 ?token=<token> 鉴权。

bash

iconhash server -p 8000
iconhash server -p 3000 --auth-token "secret"
iconhash server --host 0.0.0.0 --read-timeout 60

server 完整参数表

参数	说明
`-p, --port`	端口（默认 8000）
`--host`	绑定地址
`--auth-token`	认证令牌
`--read-timeout`	读超时（秒）
`--write-timeout`	写超时（秒）

反向代理建议

生产环境推荐用 Nginx/Caddy 反代到 iconhash server，前置 HTTPS 与限流；--auth-token 仍需保留作为应用层鉴权，二者不可互相替代。

`mcp` — MCP 服务器服务

面向 AI 代理的 stdio 协议

mcp 启动的是 stdio 模式（标准输入输出），不是 HTTP。它供 Claude Code、Cursor 等支持 MCP 的客户端通过子进程方式调用，无需端口。HTTP 暴露走 server 的 /mcp 端点。

bash

iconhash mcp

启动 stdio MCP 服务器，供 Claude Code 等 AI 代理调用。详见 MCP 集成。

`gui` — 本地 Web GUI 服务

无需配置，开箱即用

gui 启动本地 HTTP 服务并自动打开浏览器，无需安装额外前端依赖。适合不熟悉命令行、需要拖放上传图标的同事快速使用。默认监听随机端口，可用 -p 固定。

bash

iconhash gui
iconhash gui -p 8080

输出格式速查

复制即用

下表每条语法都已是可直接粘贴进对应引擎搜索框的完整查询式，无需补全引号或前缀。--engine 输出的字符串与表第三列完全一致，可脚本化拼接：iconhash url <u> --engine fofa 的 stdout 直接是 Fofa 的查询条件。

6 大搜索引擎的输出格式对照（以哈希 -1161367058 为例）：

引擎	`--engine` 值	输出语法示例
🟠 Fofa	`fofa`	`icon_hash="-1161367058"`
🔵 Shodan	`shodan`	`http.favicon.hash:-1161367058`
🟣 Censys	`censys`	`services.http.response.favicons.hash: -1161367058`
🟢 Quake	`quake`	`favicon:"-1161367058"`
🟡 ZoomEye	`zoomeye`	`favicon:"-1161367058"`
🔴 Hunter	`hunter`	`web.icon:"-1161367058"`

💡 不指定 --engine 时默认输出纯哈希值，可管道传递给其他工具。

速查表

命令速查表（点击展开）

我想…	命令
一键识别网站	`iconhash identify <url>`
单个图标哈希	`iconhash url <url>`
本地文件哈希	`iconhash file <file>`
批量处理	`iconhash batch -f <file>`
查指纹	`iconhash lookup -i <hash>`
搜指纹库	`iconhash fingerprints search <kw>`
启 API 服务	`iconhash server`
启 GUI	`iconhash gui`
接 Claude	`iconhash mcp`
Fofa 语法	加 `--engine fofa`
uint32 输出	加 `--uint32`

下一篇：HTTP API 参考。

CLI 命令手册 ​

命令全景 ​

全局参数 ​

🔢 哈希计算类 ​

url — 从 URL 计算 哈希 ​

file — 从本地文件计算 哈希 ​

base64 — 从 base64 数据计算 哈希 ​

🔍 识别发现类 ​

identify — 一键端到端识别（推荐） 推荐 ​

discover — 仅发现图标 识别 ​

batch — 批量处理 推荐 识别 ​

📚 指纹管理类 ​

lookup — 哈希查指纹 指纹 ​

fingerprints — 指纹库操作 指纹 ​

🖥️ 服务模式类 ​

server — HTTP API 服务器 服务 ​

mcp — MCP 服务器 服务 ​

gui — 本地 Web GUI 服务 ​

输出格式速查 ​

速查表 ​

CLI 命令手册

命令全景

全局参数

🔢 哈希计算类

`url` — 从 URL 计算哈希

`file` — 从本地文件计算哈希

`base64` — 从 base64 数据计算哈希

🔍 识别发现类

`identify` — 一键端到端识别（推荐）推荐

`discover` — 仅发现图标识别

`batch` — 批量处理推荐识别

📚 指纹管理类

`lookup` — 哈希查指纹指纹

`fingerprints` — 指纹库操作指纹

🖥️ 服务模式类

`server` — HTTP API 服务器服务

`mcp` — MCP 服务器服务

`gui` — 本地 Web GUI 服务

输出格式速查

速查表