algolia-cli

Algolia CLI

使用 algolia CLI 从终端管理 Algolia 搜索基础设施。

何时使用此技能，何时使用 algolia-mcp

需求	使用
写入／修改数据（导入、删除、更新记录）	algolia-cli（此技能）
管理配置（设置、规则、同义词）	algolia-cli（此技能）
身份验证（通过 OAuth 登录、登出、注册）	algolia-cli（此技能）
管理操作（API 密钥、配置文件、索引复制／移动）	algolia-cli（此技能）
备份／恢复索引	algolia-cli（此技能）
搜索查询和查看结果	algolia-mcp
分析（热门搜索、点击率、无结果查询）	algolia-mcp
推荐（相关产品、趋势内容）	algolia-mcp

经验法则： 如果用户想要读取或分析数据 → 使用 algolia-mcp。如果他们想要更改、移动或管理数据 → 使用 algolia-cli。

设置

运行 /algolia-cli:cli-setup 安装 CLI 并配置配置文件，或参阅入门指南。

提示： algolia auth login 是设置凭据最简单的方法——它会一步完成 OAuth 登录和配置文件创建。对于已有 API 密钥的非交互式／CI 设置，请使用 algolia profile add。

命令速查

身份验证

任务	命令
登录（打开浏览器）	algolia auth login
登录（按名称选择应用）	algolia auth login --app-name "My App" --default
登录（不使用浏览器／SSH）	algolia auth login --no-browser
登出	algolia auth logout
创建新账户	algolia auth signup

配置文件

任务	命令
添加配置文件（非交互式）	algolia profile add --name "default" --app-id "<ID>" --api-key "<KEY>" --default
列出配置文件	algolia profile list
移除配置文件	algolia profile remove "<name>" -y
设置默认配置文件	algolia profile setdefault "<name>"

应用

任务	命令
列出应用	algolia application list
创建应用	algolia application create --name "My App" --region CA
创建（非交互式，试运行）	algolia application create --name "My App" --region CA --dry-run
切换当前应用	algolia application select --app-name "My App"

API 密钥

任务	命令
列出 API 密钥	algolia apikeys list
创建 API 密钥	algolia apikeys create --acl search,browse --description "..." --indices "idx1,idx2"
获取 API 密钥	algolia apikeys get <key>
删除 API 密钥	algolia apikeys delete <key> -y

搜索

任务	命令
搜索索引	algolia search <index> --query "<query>"
使用筛选条件搜索	algolia search <index> --query "<query>" --filters "<filter>"
分页搜索	algolia search <index> --query "<query>" --hitsPerPage 10 --page 2

索引

任务	命令
列出所有索引	algolia indices list
删除索引	algolia indices delete <index> -y
清除记录（保留设置）	algolia indices clear <index> -y
复制索引	algolia indices copy <src> <dst> -y
仅复制设置	algolia indices copy <src> <dst> --scope settings -y
移动/重命名索引	algolia indices move <src> <dst> -y

对象（记录）

任务	命令
浏览所有记录	algolia objects browse <index>
浏览指定属性	algolia objects browse <index> --attributesToRetrieve title,price
从文件导入记录	algolia objects import <index> -F data.ndjson
从标准输入导入	cat data.ndjson | algolia objects import <index> -F -
按 ID 删除	algolia objects delete <index> --object-ids id1,id2 -y
按筛选条件删除	algolia objects delete <index> --filters "type:obsolete" -y
部分更新	algolia objects update <index> -F updates.ndjson

设置

任务	命令
获取设置	algolia settings get <index>
设置一项配置	algolia settings set <index> --typoTolerance="false"
从文件导入设置	algolia settings import <index> -F settings.json
导入设置并转发到副本	algolia settings import <index> -F settings.json -f

规则

任务	命令
浏览所有规则	algolia rules browse <index>
导入规则	algolia rules import <index> -F rules.ndjson -y
替换所有规则	algolia rules import <index> -F rules.ndjson -c -y
按 ID 删除规则	algolia rules delete <index> --rule-ids id1,id2 -y

同义词

任务	命令
浏览所有同义词	algolia synonyms browse <index>
导入同义词	algolia synonyms import <index> -F synonyms.ndjson
替换所有同义词	algolia synonyms import <index> -F synonyms.ndjson -r
按 ID 删除同义词	algolia synonyms delete <index> --synonym-ids id1,id2 -y
保存单个同义词	algolia synonyms save <index> --id my-syn --synonyms foo,bar

爬虫

任务	命令
列出爬虫	algolia crawler list
按应用列出	algolia crawler list --app-id <app-id>
获取爬虫详情	algolia crawler get <id>
仅获取配置	algolia crawler get <id> --config-only
创建爬虫	algolia crawler create <name> -F config.json
启动／恢复爬虫	algolia crawler run <id>
暂停爬虫	algolia crawler pause <id> [<id2> ...]
重新索引爬虫	algolia crawler reindex <id> [<id2> ...]
解除爬虫阻止	algolia crawler unblock <id> -y
抓取指定 URL	algolia crawler crawl <id> --urls url1,url2
使用爬虫测试 URL	algolia crawler test <id> --url <url>
使用配置覆盖进行测试	algolia crawler test <id> --url <url> -F config.json
获取抓取统计信息	algolia crawler stats <id>

大多数爬虫命令都支持 --dry-run，可在不发送请求的情况下预览请求：create、run、pause、reindex、unblock、test。

身份验证： 爬虫命令需要设置 ALGOLIA_CRAWLER_USER_ID 和 ALGOLIA_CRAWLER_API_KEY 环境变量，或在配置文件的个人资料中设置 crawler_user_id／crawler_api_key。

同义词类型指南

选择合适的同义词类型对搜索质量很重要：

• synonym（常规／双向）： 所有词条都可以互换使用。适用于两个方向上词义完全相同的情况。 示例：“sneakers” ↔ “trainers”——搜索任一词都应找到另一个词的结果。
• oneWaySynonym： 只有 input 词条会扩展为包含 synonyms，反向则不会。适用于较短或缩写词条应匹配更长或更具体的词条，但反之不成立的情况。 示例：“TV” → “television”、“flat screen”——搜索“TV”会找到“television”的结果，但搜索“television”不会返回“TV”的结果。

经验法则： 如果用户说“搜索 X 也应匹配 Y”，则使用单向同义词（input: X，synonyms: [Y]）。如果用户说“X 和 Y 应等同／可以互换”，则使用双向同义词。

描述

任务	命令
描述根命令树	algolia describe
描述命令	algolia describe search
描述子命令	algolia describe objects browse

关键约定

1. 始终使用非交互模式。 破坏性命令需要加上 -y（或 --confirm）以跳过确认提示。这包括 objects delete、indices delete/clear/copy/move、rules import/delete、synonyms delete 和 apikeys delete。如果不加 -y，CLI 会一直等待用户输入。注意：objects import、objects update 和 synonyms import 没有 -y 标志，默认以非交互方式运行。
2. ndjson 格式。 objects browse、objects import、rules browse/import 和 synonyms browse/import 使用换行分隔的 JSON（每行一个 JSON 对象），而非 JSON 数组。
3. 配置档案标志。 使用 -p <profile> 指定非默认配置档案。不加此标志则使用默认配置档案。
4. 凭据优先级。 环境变量优先于所有其他配置。解析顺序为：环境变量 > CLI 标志（--application-id、--api-key）> 配置档案配置文件 > 默认配置档案。支持的环境变量：ALGOLIA_APPLICATION_ID、ALGOLIA_API_KEY、ALGOLIA_ADMIN_API_KEY、ALGOLIA_SEARCH_HOSTS、ALGOLIA_CRAWLER_USER_ID、ALGOLIA_CRAWLER_API_KEY。如果设置了环境变量，这些凭据会忽略 --profile/-p。
5. 等待标志。 如果后续命令依赖当前操作完成（例如，导入后再搜索），请使用 -w（或 --wait）。
6. 在命令间通过管道传递数据。 在索引间复制数据：algolia objects browse SRC | algolia objects import DST -F -
7. JSON 输出。 需要机器可读的输出时，使用 --output json（或 -o json）。

常见工作流

在索引间迁移记录（筛选字段）

algolia objects browse SOURCE --attributesToRetrieve objectID,title,price \
  | algolia objects import DEST -F - -w

完整索引备份

algolia objects browse MY_INDEX > my_index_records.ndjson
algolia settings get MY_INDEX > my_index_settings.json
algolia rules browse MY_INDEX > my_index_rules.ndjson
algolia synonyms browse MY_INDEX > my_index_synonyms.ndjson

注意：设置使用 .json（标准 JSON），其他所有内容使用 .ndjson（换行分隔的 JSON）。

从备份还原

algolia objects import MY_INDEX -F my_index_records.ndjson -w
algolia settings import MY_INDEX -F my_index_settings.json -w
algolia rules import MY_INDEX -F my_index_rules.ndjson -c -y -w
algolia synonyms import MY_INDEX -F my_index_synonyms.ndjson -r -w

直接调用

如果技能没有自动触发，用户可以直接调用：

• /algolia-cli — 将完整技能加载到上下文中，用于任何 Algolia CLI 任务
• /algolia-cli:cli-setup — 安装 CLI 并配置配置档案

当请求较简短（例如“将我的数据导入 Algolia”），且技能可能不会自动触发时，这种方式很有用。

参考文档

• 入门指南 — 安装和配置档案设置
• 命令参考 — 每条命令的完整语法、标志和示例