searchapi 是一个 Rust 命令行工具，作为 SearchAPI.io 的智能体使用指南，建议优先调用已安装的二进制，而不是自行实现 HTTP 请求。
【安装与解析】工具优先从 PATH 中查找 searchapi（经 just install 后通常位于 ~/.local/bin/searchapi）。若未安装且本地有仓库，可执行 cd cli-rust && just install 或 just run -- <args>；若无仓库，则需用户自行克隆并安装（需 Rust 工具链与 just）。可用 searchapi --version 和 searchapi configure show 确认。不得打印完整 API Key，configure show 会掩码显示，也不要读取 ~/.searchapi.json。
【配置】配置保存在 ~/.searchapi.json（多环境）。使用 searchapi configure set --env prod --base-url https://www.searchapi.io/api/v1 --api-key <key> 设置，searchapi configure show 查看，searchapi configure use prod 切换。全局可用 --env <name> 覆盖，默认 base URL 为 https://www.searchapi.io/api/v1，认证由 CLI 以 Bearer 头处理。若提示未配置环境，需请用户提供密钥，不得编造。
【全局标志】--json 输出原始 JSON（用于解析/脚本），--env 选择环境，--help 或 searchapi help <cmd> 查看命令帮助。人工阅读用表格，需解析、汇总、过滤或串联时用 --json。
【命令】
- locations（免费）：将地点解析为 Google 引擎可用的 canonical_name，如
searchapi locations --q "austin" --limit 10，使用 CANONICAL 列值作为 jobs/events/news 的 --location。 - jobs：
searchapi jobs --q "nurse" --location "Austin,Texas,United States"，支持 --next-page-token 翻页；--location 本地化搜索（每次一个地点），--uule 单值且覆盖 --location；--location-contains 客户端按地点字段过滤。多地点需逐次请求循环。 - events：支持共享 Google 标志及 --chips、--page、--location-contains（匹配地点、场馆或标题）。
- news：支持 --page、--time-period（last_hour|last_day|last_week|last_month|last_year）、--sort-by most_recent、--nfpr、--filter、--location-contains（匹配标题、来源、摘要或链接）；无专门城市字段。
- maps：使用 google_maps 引擎，支持 --ll（@lat,lon,zoomz 或 @lat,lon,metersm）、--hl、--gl、--page、--location-contains；结果包含 place_id 供评论查询。
- maps-reviews：使用 google_maps_reviews 引擎，需要 --place-id 和/或 --data-id，支持 --topic-id、--sort-by（most_relevant|newest|highest_rating|lowest_rating）、--num（1–20）、--next-page-token；表格列含 RATING、USER、GUIDE、DATE、LIKES、SOURCE、TEXT，JSON 数组字段为 reviews。
- zillow：支持排序、挂牌状态、房型、价格/租金/卧室/浴室/面积/地块/建成年份、上市天数、关键词及多种布尔过滤，详见
searchapi help zillow。 - fetch-images：通用图片下载器（不发起 SearchAPI 请求），可接受 URL 或从任意 CLI JSON 中提取图片，支持 --from-json、--keys、--out、--prefix、--limit、--timeout、--dry-run、--overwrite、--json。
【推荐流程】先 locations 解析地名，再对 jobs/events/news 带 --location 查询；用 --json 获取结果后汇总标题、链接、公司、价格等信息并提供后续建议；脚本场景可管道到 jq 处理，出错时返回非零退出码。
【规则】优先使用 CLI 而非手写 curl；用户给出城市/地区时先解析地点；需要解析结果时用 --json；绝不提交或回显 API Key；标志不清楚时用 help，帮助信息为准。仓库中还包含 OpenAPI 规格（specs/*_openapi_spec.yaml）和紧凑标志表（references/commands.md）。若用户以 /searchapi 开头，将后面内容当作 CLI 参数执行。
【限制】具体调用受 SearchAPI.io 接口配额与密钥约束；单次请求仅支持一个 --location，多地点需循环；部分客户端过滤不会额外搜索其他地点；地图评论与图片等能力的具体返回数量受 API 限制。