作者：来自 Elastic Josh Mock, Matt Ryan
Elastic CLI 通过一条命令即可访问所有 Elasticsearch、Kibana 和 Cloud API，它也是 Elastic Agent Skills 运行所依赖的工具。在任何内容离开你的计算机之前，输入都会根据 JSON Schema 进行验证，而 API keys 会保存在你的操作系统密钥链中。
更多阅读：开启终端新体验：全新 Elastic CLI 实用指南（技术预览版）
上手体验 Elasticsearch：深入了解我们在 Elasticsearch Labs 仓库 中提供的示例 notebook，开始 免费云试用，或者现在就在你的本地计算机上试用 Elastic。
Elastic CLI 为每个公开的 Elastic API 提供一条命令： Elasticsearch、Kibana 以及 Elastic Cloud 的控制平面，包括 Serverless 项目。学习 elastic es search，你就已经知道 elastic kb data-views list 的行为方式。它既可以像由你操作一样轻松地由 AI 编程 agent 驱动，因此每条命令都接受 JSON 输入并输出 JSON，并且会在发送任何内容之前，根据 JSON Schema 验证输入。此外，它还会以退出代码结束，agent 可以根据该代码进行分支处理。管理员可以控制哪些命令可以运行，而 API keys 会存储到你的操作系统密钥链中，绝不会进入大型语言模型（ LLM ）对话记录。我们的 Agent Skills 现在就在其上运行。命令行界面（CLI）目前处于技术预览阶段。
开始免费试用 Elastic Cloud Serverless 或 登录 Elastic Cloud 来跟随本文操作，并通过 npm 安装 CLI：
bash
`npm install -g @elastic/cli`AI写代码为人类和 AI agent 设计 Elastic CLI
构建面向开发者的灵活工具所带来的一个有用副作用是，它们对 AI agent 也更加有用。这也是我们的 Agent Skills 现在用来完成工作的工具，从而闭合了我们在 2026 年 3 月开启的循环 ------ 当时我们宣布，用于 agent 工作流的 CLI 即将推出。
CLI 为 Elasticsearch、Kibana 和 Elastic Cloud 中的每个公开 API 提供统一的形式：相同的 flags、输入和输出约定、身份验证方式以及失败模式。一致性就是易用性特性；其他一切都建立在此基础之上。
Agent 需要的是同样的东西，只是要求更加严格。agent 不会知道如何构造一个有效的 CLI 命令，也不会注意到某个工具是否 "感觉" 不对；它需要能够解析的输出，以及能够在发送之前进行验证的输入，同时还需要能够据此进行分支处理的失败信息。无论 agent 是运行在平台上，还是运行在你的编辑器和终端中，如今它们都和人一样，成为 Elastic 的一等接口。Agent Skills，以及现在的 CLI，就是我们服务第二类 agent 的方式，因此这些需求从一开始就被构建进 CLI 的核心，而不是事后附加上去。
每条命令都支持 JSON 输入和输出
Agent 喜欢结构化文本，而几乎所有 Elastic API 本身都已经使用 JSON，因此一流的 JSON 支持是一个硬性要求。熟悉 jq 查询的开发者也会同样满意。
-
**JSON 输出：**任何命令，例如
elastic version和elastic es indices delete ...，都支持--json，它会将可由 JSON 解析的输出打印到 stdout，并且不输出任何其他内容。失败的命令会将{"error": {"code": "...", "message": "..."}}打印到 stderr。 -
**JSON 输入：**每个接受输入的命令都支持从 stdin 或通过
--input-file接收 JSON。该 JSON 中的每个顶层键也都可以作为 CLI 参数使用，并且内联参数具有更高优先级，因此你可以将较大的请求正文保存在文件中，并在每次调用时调整一两个值。 -
**JSON Schema 作为
--help输出：**向任何命令传递--help --json，它都会打印该命令输入所对应的有效 JSON Schema，这也可以很好地用于代码生成工具。elastic cli-schema会打印完整的命令树。
AI agent 可以根据其进行分支处理的退出代码
Agent 对退出代码的依赖程度和对 stdout 的依赖一样高。即使完全不读取 stdout 和 stderr，所有失败模式也都可以与成功区分开来。
安全护栏：密钥链存储、允许列表和验证
没有任何模型能够在 100% 的情况下完美地使用工具，因此面向 agent 的 CLI 应该尽可能在各个方面提供安全护栏。
-
**上下文和机密存储：**连接详细信息以类似
kubectl的方式存储在~/.elasticrc.yml中的命名上下文中；使用--use-context进行切换。API 命令从不将凭据作为 flags 接收。elastic config context add会将 API keys 写入你的操作系统密钥链（macOS、Linux、Windows），并在 YAML 中保留$(keychain:...)引用；$(env:...)、$(cmd:...)和$(file:...)也同样有效。使用--save-as创建 Serverless 项目时，其凭据会直接写入密钥链，并且绝不会将凭据打印出来，因此不会泄漏到日志或 LLM 对话记录中。 -
**允许列表/阻止列表：**配置文件中的
commands.allowed（或commands.blocked）列表可以在全局范围或针对每个上下文进行设置，从而确保只有管理员允许的命令才能运行。
markdown
`
1. commands:
2. allowed:
3. - version
4. - stack.es.search
5. - stack.es.esql.*
`AI写代码-
**验证：**每条命令都有一个 JSON Schema，因此输入会在发送任何请求之前进行验证。对于任何接受输入的命令，添加
--dry-run后，它会执行验证并退出，而不会发送任何内容。 -
**确认：**具有破坏性的命令会在终端中提示确认。在 agent 所处的非交互式会话中，如果没有
--yes，这些命令会拒绝运行，并通过结构化错误说明原因。 -
**清理：**索引、字段和管道名称都有长度限制以及禁止使用的字符。
elastic sanitize index-name '<value>'（以及field-name、pipeline-name等）会输出一个去除所有无效内容后的版本。
将 API 响应控制在 agent 的 上下文窗口 内
Elastic API 会返回大量数据，而 agent 的上下文窗口是有限的。以下三种控制方式有助于避免不必要的文本进入上下文窗口：
- 字段掩码：
--output-fields接受以逗号分隔的列表，并使用点号表示法指定嵌套字段。
arduino
`
1. elastic es info --output-fields 'name,version.number'
2. # {
3. # "name": "serverless",
4. # "version": { "number": "9.5.0" }
5. # }
`AI写代码- **字符串模板：**为了实现完全控制，
--output-template接受 mustache 风格的模板。
arduino
`
1. elastic es info --output-template 'ES version: {{ version.number }}'
4. # ES version: 9.5.0
`AI写代码- 命令配置文件：
--command-profile serverless（或者在配置中设置default_profile: serverless）会隐藏 Elastic Cloud Hosted 命令以及 Serverless 中不存在的 Elasticsearch 命名空间。这意味着需要浏览的内容更少，也意味着 agent 猜错的可能性更低。这是我们推荐 agent 使用的配置文件。
| 控制方式 | 功能 | 语法 | 使用场景 |
|---|---|---|---|
| 字段掩码 | 仅返回你指定的字段，对于嵌套字段使用点号表示法 | --output-fields 'name,version.number' |
你希望获得有效的 JSON，只是内容更少。这是 agent 解析结构化输出时的默认选择。 |
| 字符串模板 | 通过 mustache 风格的模板渲染响应 | --output-template 'ES version: {{ version.number }}' |
你需要以特定格式获取一个值，用于 shell 变量、日志行或提示词。 |
| 命令配置文件 | 隐藏与你的部署不适用的命令和命名空间 | --command-profile serverless 或 default_profile: serverless |
你希望使用更小的命令范围，让 agent 需要浏览的内容更少，也减少猜错的可能性。我们推荐 agent 使用此配置文件。 |
用于批量写入、滚动搜索和 msearch 的辅助工具
Elasticsearch 的一些最常用 API 存在一定的学习曲线，因此 elastic es helpers 对它们进行了封装：
-
scroll-search：将大型结果集以 NDJSON 形式进行流式传输，分页由你无需手动处理。 -
bulk-ingest：从文件、目录或 stdin 导入数据（NDJSON、JSON 数组或 CSV），并支持流式处理、批处理、并发和重试。 -
msearch：在一个请求中发送多个搜索请求。 -
watch：在文档写入索引时，将索引中的新文档打印到 stdout。这非常适合通过管道传输到日志工具。
elastic es 和 elastic kb 是 elastic stack elasticsearch 和 elastic stack kibana 的别名。如果我们没有提供你需要的命令，可以使用 elastic extension create 为你创建命令脚手架。
从终端搜索 Elastic 文档
如果你或你的 agent 不知道应该使用哪个 API，elastic docs search（以及 docs read 和 docs ask）可以从终端搜索 Elastic 文档，并返回 Markdown 或 --json。这些功能目前处于实验阶段。在传入 --accept-experimental 之前，你会看到一条警告，因此可以进行探索，但暂时不要针对它们编写脚本。
Bash、Zsh 和 Fish 的 Shell 补全
Bash、Zsh 和 Fish 都提供了自动补全功能，并且它们始终遵循你的 commands.allowed 或 commands.blocked 策略。
Elastic Agent Skills 如何使用 CLI
Agent Skills 教会 AI 编程 agent 如何以 Elastic 专家的方式处理工作；例如，哪个集群健康字段代表最终判断，或者如何分阶段执行重新索引以避免其崩溃。它们记录的是流程和判断，而不是传输方式。一个嵌入了带认证请求头的 curl 的 skill，会将主机名、密钥和运行时环境硬编码其中，而当其中任何一项发生变化时，它就会失效。
因此，我们的 skills 现在使用一种_通用_格式，可以在任何能够执行 elastic CLI 的运行时中保持不变地运行，包括 Claude Code、Codex、Cursor 和 GitHub Copilot。正文使用 HTTP 简写形式引用操作（GET /_cluster/health、POST /_query），并在末尾提供一个操作表，将每项操作绑定到一个 CLI 命令。该表是传输方式出现的唯一位置：
| HTTP API（简写） | elastic CLI 命令 |
|---|---|
GET /{index}/_mapping |
elastic es indices get-mapping --index '<index>' |
POST /_query |
elastic es esql query --format tsv --query "<esql>" |
POST cloud:/api/v1/serverless/projects/elasticsearch |
elastic cloud serverless projects search create --input-file <json> --wait --save-as <ctx> |
每个通用 skill 还会继承一段直接明确的前置说明；也就是说，使用 CLI，不要猜测凭据，不要直接调用 HTTP API，也绝不要要求用户将 API key 粘贴到聊天中。
这两个部分彼此需要对方。skill 提供模型所不具备的专业知识，而 CLI 则提供了一种经过验证、凭据安全并受你的允许列表限制的执行方式。告诉你的 agent 启动一个 Serverless 项目并将 products.csv 加载进去 ，配置 skill 就会使用 --save-as 创建项目。导入 skill 会对映射执行试运行，然后使用 elastic es bulk 加载数据，而 Elasticsearch Query Language（ES|QL）skill 会编写一个第一次尝试就能解析成功的查询。每一步都会返回 JSON，失败时以非零状态码退出，并且只能执行你的策略所允许的操作。
目前已经提供用于 Elastic Cloud 入门和配置、Elastic Workflows 以及 Kubernetes 调查的 skills。用于 Elasticsearch 查询、数据导入、重新索引和索引设计，以及 Kibana 仪表板和告警的 skills 也即将推出。
Elastic CLI 技术预览版包含什么，以及下一步是什么
该预览版涵盖所有公开的 Elasticsearch Serverless、Kibana Serverless 和 Elastic Cloud API。仅适用于 Hosted 的 9.x Elasticsearch API 覆盖率已经接近 100%，仅适用于 Hosted 的 9.x Kibana API 也将很快加入。
我们正在积极规划更多开发者体验方面的工作，包括更广泛地覆盖所有受支持的 Stack 版本、为常见工作流提供更多辅助工具、在公共目录中提供更多 skills，以及将相同的 skills 加载到运行在 Elastic 平台本身上的 agent 中。这个列表最终会如何形成，取决于我们听到的你和你的 agent 如何使用 CLI。请告诉我们哪些地方使用起来不方便、缺少哪些功能，以及你接下来希望自动化什么。
安装 Elastic CLI 和 Agent Skills
Elastic CLI 目前已经可以通过 npm 获取（Node.js 22+）。同时安装 CLI 和 skills：
sql
`npm install -g @elastic/cli # 或：npx -y @elastic/cli --help`AI写代码
bash
`npx skills add elastic/agent-skills`AI写代码然后添加一个上下文并进行检查：
arduino
`elastic config context add prod --es-url https://<project>.es.us-east-1.aws.elastic.cloud --es-api-key <KEY>`AI写代码
go
`elastic status`AI写代码即使没有项目，你也可以在大约一分钟内开始免费 Serverless 试用，无需信用卡。如果你已经拥有项目，请登录，并为 Elastic Cloud 和你的 Elasticsearch 集群创建 API keys。在让 agent 连接任何真实环境之前，先从试用项目、只读密钥以及范围受限的 commands.allowed 列表开始。请务必花五分钟阅读 skills 仓库中的安全说明。
将 Bash 脚本中的所有 curl 命令替换掉，并在你的 AGENTS.md 中添加一些使用说明。然后让你的 agent 的 skills 高效、准确地使用我们的 API。告诉我们你的想法，如果你发现 bug 或者你的使用场景没有得到良好支持，也不要犹豫，提交 issue。你的反馈会直接影响我们下一步构建的内容。
Elastic CLI 和 Agent Skills 资源
-
报告 CLI 问题 · 报告 skills 问题 · 讨论
原文：Elastic CLI: One command for every API, built for agents | Elasticsearch Labs