# @elastic/cli 中文文档

规范地址：https://npmcn.com/package/%40elastic/cli/

版本：0\.7\.0
npm 元数据更新时间：2026-10-15T19:11:52.618Z
中文译文更新时间：2026-11-13T11:11:26.501Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40elastic/cli
原文对照：https://npmcn.com/package/%40elastic/cli/?lang=original
项目主页：https://github.com/elastic/cli#readme
源码仓库：https://github.com/elastic/cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，437 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.1\.0
- 运行依赖：12 个
- 首次发布：2026-05-12T19:48:05.364Z
- 最新版本发布：2026-10-15T19:11:52.230Z
- 近 30 天下载量：6424（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

与命令行的"弹性堆栈"和"弹性云"交互.

## 安装

```sh
npm install @elastic/cli
```

也可以使用：`pnpm add @elastic/cli`、`yarn add @elastic/cli`、`bun add @elastic/cli`

## README

# 弹性 CLI

与命令行的"弹性堆栈"和"弹性云"交互.

## : 警告: 技术预览

此 CLI 工具是一个 **技术预览** 并且仍在积极发展之中。 它尚未支持每个版本的"弹性堆栈"中所有可用的功能和API.

## 安装

从 npm 向全球安装 `elastic` 您的二进制可用 `PATH`数字 :

```bash
npm install -g @elastic/cli
elastic --help
```

如果您不希望全局安装, 您可以运行一次性引用 `npx`,它下载和运行 CLI 而不坚持:

```bash
npx -y @elastic/cli --help
```

> 若为 `npm install -g` 失败 `EACCES` linux/macOS 上的权限错误, 或重新运行 `sudo` 或(被推荐) npm 的全局前缀 a 用户拥有的目录 :
> 
> ```bash
> mkdir -p ~/.npm-global
> npm config set prefix ~/.npm-global
> echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
> source ~/.bashrc
> ```

## 对于特工

偏爱 `elastic <command> --help --json` 一个命令和 `elastic cli-schema` 为整棵树。 不要摄入 `docs/cli/schema.json` 直接说.

## 壳完成

`elastic completion <shell>` 打印将 CLI 连接到的包装脚本 您的外壳的标签补全系统。 巴什,兹什,和菲什都得到了支持.

包装是动态的: 每个 `<tab>` 弹壳向外 `elastic` 问 候选人申请,所以完成时间与已安装的 CLI 版本同步 并包含您配置文件中的上下文名称.

### 巴许

```bash
# System-wide (writable by root):
elastic completion bash | sudo tee /etc/bash_completion.d/elastic > /dev/null

# Per-user (no sudo required):
mkdir -p ~/.local/share/bash-completion/completions
elastic completion bash > ~/.local/share/bash-completion/completions/elastic
```

然后打开一个新的外壳.

### 日语

```bash
# Drop the script into the first directory in $fpath:
elastic completion zsh > "${fpath[1]}/_elastic"

# Make sure compinit is enabled in ~/.zshrc:
autoload -Uz compinit && compinit
```

或者,对于当前会话中的一发安装:

```bash
eval "$(elastic completion zsh)"
```

### 鱼

```fish
elastic completion fish > ~/.config/fish/completions/elastic.fish
```

Fish自动取出新的完成文件.

### 动力壳

```powershell
elastic completion powershell | Out-File -Encoding utf8 -Append $PROFILE
```

然后打开一个新的PowerShell会话.

### 完成的东西

-   顶级命令和组( X)`stack`, (中文(简体) ), `cloud`, (中文(简体) ), `docs`, (中文(简体) ), `config`, (...) (中文(简体) )
-   每个深度的嵌入子命令
-   长选项旗( N)`--json`, (中文(简体) ), `--use-context`,命令特定选项)
-   用于 `--use-context` (从活动配置文件读取)
-   这个 `es` 编号 : `kb` 别名的工作与犬科相同 `stack es` 编号 : `stack kb` 表单

完成时尊重活动 `commands.allowed` 编号 : `commands.blocked` 政策: 命令限制自己不能作为候选人出现.

## 配置

CLI 在您的主目录中寻找一个配置文件 。 下列文件名 选中( 按此顺序) :

1.  `.elasticrc`
2.  `.elasticrc.json`
3.  `.elasticrc.yaml`
4.  `.elasticrc.yml`

将您的配置放置于 `~/.elasticrc.yml` (建议.

要使用不同位置的配置文件, 请通过 `--config-file <path>` 或设置 页:1 `ELASTIC_CLI_CONFIG_FILE` 环境变量。 国旗优先 超过环境变量.

```yaml
current_context: local

contexts:
  local:
    elasticsearch:
      url: http://localhost:9200
      auth:
        api_key: your-api-key-here
    kibana:
      url: http://localhost:5601
      auth:
        api_key: your-api-key-here
  staging:
    elasticsearch:
      url: https://my-cluster.es.us-east-1.aws.elastic.cloud
      auth:
        api_key: your-api-key-here
    cloud:
      url: https://api.elastic-cloud.com
      auth:
        api_key: your-cloud-api-key-here
```

支持多种背景. 覆盖 `current_context` 单项命令 `--use-context <name>`。 。 。 .

每种上下文都可能有组合的服务块(`elasticsearch`, (中文(简体) ), `kibana`, (中文(简体) ), `cloud`) (中文(简体) ). 认证也可以使用 `username` + 键 `password` 改为 `api_key`。 。 。 .

### 作者 CLI 的配置

而不是手工编辑YAML `elastic config` 命令组创建和 在OS 键链中保存上下文并存储已有的秘密 (MacOS Keychain, Linux libsecret,,,,,,,,,,,, `pass`, Windows 证书管理器). 也门 然后持有一个 `$(keychain:...)` 编号 : `$(secret_service:...)` / 等解析器 而不是生来的秘密.

```bash
# Add a new context (API key goes to the keychain; YAML gets $(keychain:...))
elastic config context add local \
  --es-url http://localhost:9200 \
  --es-api-key your-api-key

# List contexts (the current one is marked)
elastic config context list

# Switch the active context
elastic config current-context set staging

# Flag-patch an existing context
elastic config context edit local --es-url http://localhost:9201

# Open the context as YAML in $EDITOR for free-form edits
elastic config context edit local

# Remove a context (keychain entries are cleaned up)
elastic config context remove old-lab
```

如果没有 OS 键链( 或者您通过) `--inline-secrets`这秘密是 写入内置文件 `chmod 0600`时发出警告 装入的配置在比0600权限松散时有内含的秘密.

### B. 信誉安全项目的创建

关于代理/LLM工作流程, `serverless projects create` 财务报告和审定财务报表 `reset-credentials` 接受 `--save-as <context>` 避免通过 stdout 泄露管理证书:

```bash
elastic cloud serverless projects search create --wait --save-as scratch \
  --name scratch-es --region-id aws-us-east-1

# stdout has endpoints + a `savedAs: scratch` marker, password is redacted.
# The keychain now holds scratch:elasticsearch.auth.password etc.
elastic --use-context scratch es indices list

# Rotate creds; URL stays, only the password moves.
elastic cloud serverless projects search reset-credentials --id <id> \
  --save-as scratch --force
```

`--credentials-file <path>` 是写独立 YAML 的选项 配置碎片( 0600) 时间 `<path>` 而不是改变主配置。 无论是 旗帜可以让Stdout安全地捕捉到 LLM 记录.

### 外部证书

配置文件中的任何字符串值都能够 使用情况 `$(resolver:params)` 从外部来源获取值的表达式 运行时间.

> **安全说明.** 在使用配置文件前审查配置文件, 如果你不写 他们自己—— `$(cmd:...)` 财务报告和审定财务报表 `$(file:...)` 解析器执行程序 并代表您阅读文件。 这尤其适用于氯氟化物/催化物的环境 重新检查的配置(例如通过) `ELASTIC_CLI_CONFIG_FILE`)可以运行 任意命令运行者.

#### `file` - 从文件读取

读取文件的内容( trimmed) 。 对Docker/Kubernetes秘密有用 装入时间 `/run/secrets/`。 。 。 .

```yaml
auth:
  api_key: $(file:/run/secrets/elastic_api_key)
```

#### `env` - 环境变量

```yaml
auth:
  api_key: $(env:ELASTIC_API_KEY)
```

#### `cmd` - shell 命令输出

命令被执行,其stdout(trimmed)被用作值.

```yaml
auth:
  api_key: $(cmd:pass show elastic/api-key)
```

#### `keychain` - macOS 键链(只有macOS)

使用 macOS 密钥链读取密码 `service/account` 格式.

```yaml
auth:
  api_key: $(keychain:elastic-cli/api-key)
```

要存储一个值 : `security add-generic-password -s elastic-cli -a api-key -w`

#### `secret_service` - 免费桌面特勤服务(仅限Linux)

通过 GNOME 键盘或 KWallet 读取一个秘密 `secret-tool`。使用相同的 `service/account` 格式为 `keychain`。 。 。 .

```yaml
auth:
  api_key: $(secret_service:elastic-cli/api-key)
```

要存储一个值 : `secret-tool store --label='Elastic API Key' service elastic-cli account api-key`

#### `pass` - 标准 Unix 密码管理器(跨平台)

读取第一行 `pass show`. 工作在 Linux, macOS, 和 Windows (WSL)上.

```yaml
auth:
  api_key: $(pass:elastic/api-key)
```

要存储一个值 : `pass insert elastic/api-key`

#### `credential_manager` - Windows证书管理器(仅Windows)

使用 Windows 证书管理器读取证书 `service/account` 格式。 要求 `CredentialManager` 动力壳模块.

```yaml
auth:
  api_key: $(credential_manager:elastic-cli/api-key)
```

要存储一个值 : `New-StoredCredential -Target elastic-cli/api-key -UserName _ -Password <key>`

表达式可以出现在任何字符串字段中,包括 URL :

```yaml
elasticsearch:
  url: https://$(env:ES_HOST):9200
  auth:
    api_key: $(keychain:elastic-cli/api-key)
```

## 全球备选方案

| 选项 | 说明 |
| --- | --- |
| `--config-file <path>` | 配置文件的路径( 默认 ): `~/.elasticrc.yml`(中文(简体) ) |
| `--use-context <name>` | 从配置文件中覆盖活动上下文 |
| `--command-profile <name>` | 将可用命令限制在部署配置文件( Q)`full`, (中文(简体) ), `serverless`(中文(简体) ) |
| `--json` | 作为JSON的产出结果 |
| `--output-fields <list>` | 以逗号分隔的要包含在输出中的字段列表( 支持 dot- 注释) |
| `--output-template <string>` | 用于自定义文本输出的类似胡子的模板(例如. `"{{id}}: {{name}}"`(中文(简体) ) |
| `--dry-run` | 验证所有输入和退出而不执行任何动作 |

## 图标

### `version`

打印CLI版本.

```bash
elastic version
elastic --json version
```

### `stack` 编号 : `es` 编号 : `kb` - 弹性堆栈

与弹性堆栈组件交互. `es` 财务报告和审定财务报表 `kb` 作为顶级工作 快捷键与完整 `stack es` 编号 : `stack kb` 路径 :

```bash
elastic es --help                # same as: elastic stack es --help
elastic kb --help                # same as: elastic stack kb --help
elastic stack --help
elastic stack es --help          # or: elastic stack elasticsearch --help
elastic stack kb --help          # or: elastic stack kibana --help
```

#### `es` - 弹性搜索API

运行 Elasticsearch API 调用. 命令直接映射到 Elasticsearch API 端点.

全体 `es` 子命令支持 :

| 选项 | 说明 |
| --- | --- |
| `--dry-run` | 验证输入和退出而无需调用 API |
| `--input-file <path>` | 从 JSON 文件装入命令输入而不是 CLI 旗 |
| `--no-validate` | 跳过输入验证并发送请求为-is( schema 不匹配的逃出舱; 仅可用带有 JSON Schema 输入的命令) |

**子命令组** (每个都有自己的子命令):

-   `async-search` - 自动搜索 API
-   `cat` - 猫的API
-   `cluster` - 集群管理
-   `connector` - 连接器管理
-   `enrich` - 丰富政策
-   `eql` - EQL搜索
-   `esql` - ESQEL查询
-   `indices` - 指数管理
-   `inference` - 推断终点
-   `ingest` - 摄入管
-   `license` - 许可证管理
-   `logstash` - 日志管线
-   `ml` - 机器学习
-   `project` - 项目管理
-   `query-rules` - 查询规则
-   `search-application` - 搜索应用程序
-   `security` - 安全APIs
-   `sql` - SQL查询
-   `synonyms` - 同义词集
-   `tasks` - 任务管理
-   `transform` - 变身

**顶级 `es` 命令** (实例):

```bash
elastic es search --index my-index
elastic es get --index my-index --id abc123
elastic es index --index my-index --id abc123
elastic es delete --index my-index --id abc123
elastic es count --index my-index
elastic es info
elastic es bulk
elastic es reindex
elastic es update --index my-index --id abc123
```

运行 `elastic es <command> --help` 用于任何命令上的所有可用选项.

#### `kb` - 基巴纳 API

运行 Kibana API 呼叫。 命令按命名空间组织(例如:. `data-views`, (中文(简体) ), `cases`, (中文(简体) ), `alerting`) (中文(简体) ). 需要一个 `kibana` 活动上下文中的服务块.

全体 `kb` 子命令支持 :

| 选项 | 说明 |
| --- | --- |
| `--dry-run` | 验证输入和退出而无需调用 API |
| `--input-file <path>` | 从 JSON 文件装入命令输入而不是 CLI 旗 |
| `--no-validate` | 跳过输入验证并发送请求为-is( schema 不匹配的逃出舱; 仅可用带有 JSON Schema 输入的命令) |

```bash
elastic kb data-views list
elastic kb data-views get --data-view-id <id>
elastic kb cases list
elastic kb alerting list-rule-types
```

运行 `elastic kb <namespace> --help` 用于命名空间中所有可用的命令.

### `cloud` - 有弹性的云

管理弹性云:主机部署和无服务器项目. 需要一个 `cloud` 活动上下文中的服务块.

树有三种子

-   交叉取名空间作为 `cloud` (适用于 无论是主机还是服务器).
-   `cloud hosted …` 为主机部署 API.
-   `cloud serverless …` 用于无服务器工程 API.

#### 交叉(信任、认证、orgs、用户、计费)

```bash
elastic cloud trust get-current-account
elastic cloud auth get-api-keys
elastic cloud orgs list-organizations
elastic cloud orgs get-organization --organization-id <id>
elastic cloud users add-role-assignments --user-id <id> <<< '{...}'
elastic cloud billing get-costs-overview
```

#### `cloud hosted` - 主办部署

```bash
elastic cloud hosted deployments list-deployments
elastic cloud hosted deployments get-deployment --id <id>
elastic cloud hosted deployments shutdown-deployment --id <id>
elastic cloud hosted deployments create-deployment <<< '{"name":"my-deployment",...}'
elastic cloud hosted deployment-templates list-deployment-templates
elastic cloud hosted traffic-filters get-traffic-filter-rulesets
elastic cloud hosted extensions list-extensions
elastic cloud hosted stack get-version-stacks
```

运行 `elastic cloud hosted --help` 用于所有可用的命名空间组 (部署 -- -- 平板、部署、交通过滤、扩展、堆放、信任的环境).

#### `cloud serverless` - 无服务器项目

```bash
elastic cloud serverless projects search list
elastic cloud serverless projects search create <<< '{"name":"demo","region_id":"aws-us-east-1"}'
elastic cloud serverless projects search create --wait <<< '{"name":"demo","region_id":"aws-us-east-1"}'
elastic cloud serverless projects search get --id <id>
elastic cloud serverless projects search delete --id <id>
elastic cloud serverless projects search get-status --id <id>
elastic cloud serverless projects search get-roles --id <id>
elastic cloud serverless projects search reset-credentials --id <id>
```

`search` 还接受 `elasticsearch` 作为别名. 同样的命令可用 下级 `observability` 财务报告和审定财务报表 `security`数字 :

```bash
elastic cloud serverless projects observability list
elastic cloud serverless projects security create --wait <<< '{"name":"demo","region_id":"aws-us-east-1"}'
```

其他无服务器资源 :

```bash
elastic cloud serverless regions list-regions
elastic cloud serverless traffic-filters list-traffic-filters
elastic cloud serverless cross-project get-elasticsearch-project-link-candidates
```

运行 `elastic cloud serverless --help` 对所有可用的群体.

## 扩展

扩展为 CLI 添加了新的顶级子命令 。 一旦安装, 一个扩展名将命名 `demo` 被援引为 `elastic demo`。 。 。 .

### 安装扩展

```bash
# from a GitHub repository (github:owner/repo or shorthand owner/repo)
elastic extension install github:elastic/elastic-demo
elastic extension install elastic/elastic-demo

# from an npm package
elastic extension install npm:elastic-demo
```

CLI 克隆或将扩展安装到 `~/.elastic/extensions/elastic-<name>/`,从 `package.json` bin field,并注册它。 如果存储器包含 `package.json`, (中文(简体) ), `npm install --production` 在克隆后自动运行.

### 创建本地扩展名

`extension create` 脚手架上安装了一个新的扩展并登记在一个步骤中. 这是开始写自己扩展的最快方法.

```bash
# create a fresh extension at ~/.elastic/extensions/elastic-my-tool/
elastic extension create my-tool

# register an existing directory as a local extension (files are not overwritten)
elastic extension create demo --path ./path/to/my-extension
```

脚手架 `index.js` 是一个可运行的起点,用于在当前背景下输出 JSON。 编辑以实施真实逻辑.

CLI通过环境变量将活性上下文传递到每一个扩展上下文,然后产生:

| 变量 | 说明 |
| --- | --- |
| `ELASTIC_ES_URL` | 从活动上下文进行弹性搜索 URL |
| `ELASTIC_ES_API_KEY` | 弹性搜索 API 密钥 |
| `ELASTIC_KIBANA_URL` | 基巴纳 URL |
| `ELASTIC_KIBANA_API_KEY` | Kibana API 密钥 |
| `ELASTIC_CLOUD_URL` | 弹性云 API URL |
| `ELASTIC_CLOUD_API_KEY` | 弹性云 API 密钥 |

### 管理扩展

```bash
# list installed extensions
elastic extension list

# upgrade one extension (github and npm sources only)
elastic extension upgrade my-tool

# upgrade all extensions
elastic extension upgrade

# remove an extension
elastic extension remove my-tool
```

### 演示扩展

这个 `examples/extensions/basic/` 此 repo 中的目录包含一个最小的工作示例 。 在当地注册:

```bash
elastic extension create demo --path ./examples/extensions/basic
elastic demo
```

## 常见问题

### @elastic/cli 是什么？

与命令行的"弹性堆栈"和"弹性云"交互\.

### 如何安装 @elastic/cli？

在项目目录运行 npm install @elastic/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 elastic，可以用 npx elastic 直接运行。

### @elastic/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @elastic/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @elastic/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.1\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @elastic/cli 可以商用吗？

@elastic/cli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @elastic/cli 的下载量有多少？

根据 npm 官方下载统计，@elastic/cli 在 2026/10/13 – 2026/11/11 这 30 天内被下载 6,424 次，日均约 214 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @elastic/cli 还在维护吗？

最新版本 0\.7\.0 发布于 2026/10/16（28 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。