# @dotcms/dotcli 中文文档

规范地址：https://npmcn.com/package/%40dotcms/dotcli/

版本：26\.11\.17-1
npm 元数据更新时间：2026-11-17T16:02:05.897Z
中文译文更新时间：2026-11-17T16:04:02.325Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：282 MB，6 个文件
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2024-02-07T21:26:59.883Z
- 最新版本发布：2026-11-17T16:02:05.592Z
- 近 30 天下载量：8685（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：1061（近 12 个月 452 个）

## 中文简介

管理dotCMS内容的官方命令行工具.

## 安装

```sh
npm install @dotcms/dotcli
```

也可以使用：`pnpm add @dotcms/dotcli`、`yarn add @dotcms/dotcli`、`bun add @dotcms/dotcli`

## README

# 点点CMS CLI

这个 **点点CMS CLI**,有时缩短为 **点CLI**,是一个通过命令外壳与点CMS实例相互作用的独立工具,允许大量自动化操作和行为.

## 开始

### 安装

### 国家预防机制

最简单和最推荐的方法是从它的npm软件包中获取点CMS CLI:

```shell
npm install -g @dotcms/dotcli
```

### 手动 JAR 下载

1.  下载 CLI : 点CMS CLI 作为可下载的 uber 罐子发送 [这里](https://dotcms-repo.b-cdn.net/libs-release/com/dotcms/dotcms-cli/)。 。 。 . 一旦下载,你只需要运行它与:

```shell
java -jar dotcli.jar
```

2.  配置您想要连接到的点CMS 实例 `config` 命令。 更多关于如何做到这一点的细节 [配置](https://npmcn.com/package/%40dotcms/dotcli/#readme-Configuration) 节.
    
3.  登录到选中实例
    

```shell
java -jar dotcli.jar login --user={USER} --password  
```

## 可用命令

| 命令 | 说明 |
| --- | --- |
| [配置](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/config.adoc) | 设定所有命令运行所需的初始配置 |
| [内容类型](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/content-type.adoc) | 在内容类型上进行操作。 例如:拉出、推出、去掉 |
| [文件](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/files.adoc) | 对文件进行操作 。 例如:树, Is, 推 |
| [实例](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/instance.adoc) | 打印可用的点CM 实例列表 |
| [语言](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/language.adoc) | 执行语言操作。 例如:拉出、推出、去掉 |
| [登录](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/login.adoc) | 登录到点CMS 实例 |
| [推动](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/push.adoc) | 用于同步 GitHub Repo 和目标点CMS 环境的全局驱动命令 |
| [牵出](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/pull.adoc) | 全局拉动命令用于同步目标点CMS环境与本地工作空间 |
| [站点](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/site.adoc) | 在现场进行操作。 例如:拉出、推出、去掉 |
| [状态](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/status.adoc) | 提供当前登录用户和点CMS实例状态的信息 |

您可以找到更多关于如何使用点CMS CLI的细节 [实例](https://npmcn.com/package/%40dotcms/dotcli/#readme-examples) 节.

## 实例

1.  运行配置命令以设定所有命令运行所需的初始配置

```shell
config 
Enter the key/name that will serve to identify the dotCMS instance (must be unique) [local].
The name is [local]
Enter the dotCMS base URL (must be a valid URL starting protocol http or https) [http://localhost:8080]
The URL is [http://localhost:8080]
Are these values OK? (Enter to confirm or N to cancel)  (Y/n)
...
Do you want to continue adding another dotCMS instance?  (Y/n)n
 0. Profile [local], Uri [http://localhost:8080], active [no].
 1. Profile [local#1], Uri [https://demo.dotcms.com], active [no].
One of these profiles needs to be made the current active one. Please select the number of the profile you want to activate. 1
```

2.  登录管理员用户

```shell
login --user=admin@dotCMS.com --password
```

2.  列出并选择我们要运行的点CMS 实例

```shell
instance --list
```

3.  激活一个名为 DotCMS 实例描述文件 `demo`

```shell
instance --activate demo
```

4.  获取当前实例的信息运行

```shell

status
    
#You will get an output similar to:
2023-02-22 11:25:29,499 INFO  [com.dot.api.cli.HybridServiceManagerImpl] (Quarkus Main Thread) Service [default] is missing credentials.
2023-02-22 11:25:29,500 INFO  [com.dot.api.cli.HybridServiceManagerImpl] (Quarkus Main Thread) Service [demo] is missing credentials.
Active instance is [demo] API is [https://demo.dotcms.com/api] No active user Use login Command.
```

5.  调取内容类型

```shell
content-type pull FileAsset
```

6.  创建新站点

```shell
site create "my.cool.bikes.site.com"
```

## 构建 CLI( dev 模式)

CLI是一个由两个模块组成的 quarkus/pico-cli项目 [语气](https://npmcn.com/package/%40dotcms/dotcli/cli) 财务报告和审定财务报表 [api-data-模块](https://npmcn.com/package/%40dotcms/dotcli/api-data-model)。 。 。 . 这个项目作为母体反应堆的堆积。 您可以在顶层构建模块.

```shell
./mvnw clean install -DskipTests=true
```

我们建议建造该项目,而不考虑测试执行(`-DskipTests=true`) (中文(简体) ). 它将运行更快,并避免建立测试环境.

#### 运行 CLI( dev 模式)

你可能会用 [夸克克克立语name](https://es.quarkus.io/guides/cli-tooling) 或者说 [母亲](https://maven.apache.org/install.html) 首先,在当地启动一个点CMS实例. 然后,执行以下命令

```shell
# from top level to build all
cd cli
# command is same as the following to run the quarkus build plugin
# ../mvnw quarkus:dev 
quarkus dev
```

**注:** 为了减少多模块项目中的重复,mvnw不包含在每个子模块上. 夸克斯命令找到可执行文件

从子模块运行 mvnw 只需使用相对路径到父 mvn. 如果从子模块文件夹运行, 所有依赖需要更新并安装到本地的 mvn 并安装 Maven

或者,您可以从父文件夹中指定子文件夹

```shell
# from top level to build all
cd cli
# The command is same as the following to run the quarkus build plugin
# ../mvnw quarkus:dev 
../mvnw -pl cli quarkus:dev
```

一旦cli以dev模式启动,它就会打印出一份可用的命令列表.

接下来是

```shell
--
Tests paused
Press [space] to restart, [e] to edit command line args (currently ''), [r] to resume testing, [o] Toggle test output, [:] for the terminal, [h] for more options>
```

我们还可以指示 Quarkus dev 模式使用预设的参数启动我们的cli,方法是:

```shell
../mvn quarkus:dev -Dquarkus.args=status
```

这将启动 cli 直接传入其中的参数, 让他们执行命令状态 .

## 建造一个CLI罐

要将 cli 生成为装有所有必要依赖的罐子包,您需要运行以下命令: `cli` 目录 :

```shell
../mvnw clean install package
```

所有命令都可以直接从生成的罐子中执行,这些罐子可以在下面找到 `cli/target/quarkus-app/`。 。 。 .

示例

```shell
java -jar ./cli/target/quarkus-app/quarkus-run.jar status
```

## 日志

运行 CLI 时, a **_dotcms-cli.log (英语)_** 文件将在 CLI 的目录中创建 可执行文件正在运行 .

#### 文件日志级别

将文件日志级别增加至 _吉布提_ 在dev模式下运行时,使用以下命令:

```shell
../mvnw quarkus:dev -Dquarkus.log.file.level=DEBUG
```

#### 控制台日志级别

将控制台日志级别增加至 _吉布提_ 在dev模式下运行时,使用以下命令:

```shell
../mvnw quarkus:dev -Dquarkus.log.handler.console.\"DOTCMS_CONSOLE\".level=DEBUG
```

#### 文件日志位置

要覆盖日志文件的默认位置, 您有两个选项:

##### 1\. 设定环境变量

示例

```shell
export QUARKUS_LOG_FILE_PATH=/Users/my-user/CLI/dotcms-cli.log
java -jar cli-1.0.0-SNAPSHOT-runner.jar login -u admin@dotcms.com -p
```

##### 2\. 设定系统属性

示例

```shell
../mvnw quarkus:dev -Dquarkus.log.file.path=/Users/my-user/CLI/dotcms-cli.log
```

## 配置

CLI可用于管理多点CMS实例. 每个实例描述文件在 `~/.dotcms/dot-service.yml` 文档. 使用 CLI 执行命令 通过运行 `status` 命令. 这里有一个默认的例子 `dot-service.yml` 与 CLI 一起传送的文件 :

```yaml
- name: "default"
  url: "http://localhost:8080"
  credentials:
    user: "admin@dotcms.com"
- name: "demo"
  url: "https://demo.dotcms.com"
  active: true
  credentials:
    user: "admin@dotCMS.com"
```

因此,为了添加一个新的实例配置,您需要在 `dot-service.yml` 如上面的例子所示. 这个 `active` 属性表示当前活动的配置文件。 CLI 将使用活性配置文件执行命令. 如果一个以上的配置文件被标记为活动,这将导致无效状态例外 . 这个 `credentials` 区域是可选的。 如果不提供证书,CLI将提示用户在 `login` 命令已执行.

如果 `dot-service.yml` 文件不存在, CLI 将提示创建一个没有有效配置就无法操作的命令 .

CLI提供 `config` 命令来设置所有命令运行所需的初始配置。 命令将引导您完成在新实例配置中添加的进程 `dot-service.yml` 文档。 并设置活动配置. 见 [配置](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/config.adoc) 详细情况。 还有 [实例](https://npmcn.com/package/%40dotcms/dotcli/#readme-examples) 一节作为实例.

### 工作空间

CLI需要一个工作空间,才能将内容拉出并推向一个点CMS实例. 工作空间基本上是一套目录和文件,用来存放和组织CLI可以管理的不同类型的资产. 此外,一个名为 `.dot-workspace.yml` 向 CLI 显示当前目录是一个有效的工作空间. 在下表中,您可以看到符合工作空间的不同目录和文件.

| 文件/目录 | 类型 | 说明 |
| --- | --- | --- |
| `content-types/` | 目录 | 内容 - 类型目录 |
| `files/` | 目录 | 文件目录 |
| `languages/` | 目录 | 语言目录 |
| `sites/` | 目录 | 站点目录 |
| `.dot-workspace.yml` | 文件 | CLI 工作空间标记 |

## 使用.dotcliignore 过滤文件

在将文件推向 dotCMS 时,可以通过创建 `.dotcliignore` 文档。 此文件工作类似 `.gitignore` 并支持标准光标模式.

### 图案语法

这个 `.dotcliignore` 文件支持以下 glob 模式 :

-   `*` - 匹配单个目录级别内任意字符序列
-   `**` - 匹配多个目录级别的任意字符序列
-   `?` - 匹配任何单一字符
-   `[]` - 匹配字符类(例如, `[abc]` 或者说 `[0-9]`(中文(简体) )
-   `!` - 取消重新纳入先前排除的文件的模式

### 等级式加载

CLI 负载 `.dotcliignore` 从当前目录到工作空间根的分级文件。 儿童目录中定义的模式优先于父母目录,允许您凌驾于父母排除之外.

### 用法实例

创建一个 `.dotcliignore` 在工作空间中,有下列图案:

```
# Ignore all log files
*.log

# Ignore build directories
build/
dist/
target/

# Ignore OS-specific files
**/.DS_Store
**/Thumbs.db

# Ignore dependencies
node_modules/
vendor/

# Re-include a specific log file (negation)
!important.log
```

### 页:1

-   以 `#` 作为评论处理
-   空行被忽略
-   引导和后导的白空间自动从模式中去除
-   为了以图案保存后方空间 `pattern\`
-   相对于工作空间根评价模式
-   目录模式应以 `/`
-   匹配被忽略模式的文件将在 `files push` 业务
-   牵引作业不受 `.dotcliignore` 文件

## GitHub 动作集成

我们为GitHub Actions提供支持,以便能够作为你们CI/CD管道的一部分运行CLI.

以下的例子说明如何创建全新的寄存器,并用CLI工作空间来种子. 为了将CLI纳入您的 GitHub 动作工作流程, 您需要:

-   创建 GitHub 仓库来管理您的点CMS 资产 .
    
-   复制 [动作](https://npmcn.com/package/%40dotcms/dotcli/action) 输入您的根项目 `.github/workflows` 目录.
    
-   在您的仓库常规设置中, 启用以下权限 :
    
    -   工作流程权限 : 读写权限
-   在您的仓库常规设置、 秘密和变量、 动作
    
    -   创建名为新变量的变量 `DOT_API_URL` ,并将值设置为有效的点CMS URL。 譬如说. `https://demo.dotcms.com` ![How to create a variable](https://npmcn.com/package/%40dotcms/dotcli/doc_images/create_variable.png)
    -   创建一个名为新秘密 `DOT_TOKEN` ,然后将值设置为有效的点CMS CLI 符号. ![How to create a secret](https://npmcn.com/package/%40dotcms/dotcli/doc_images/create_secret.png)
-   以 CLI 工作空间种子您的本地仓库
    
    -   通过运行任何拉动命令,例如可以创建cli工作空间. `java -jar dotcli.jar files pull //demo.dotcms.com`
    -   运行您工程根的牵引命令 [实例](https://npmcn.com/package/%40dotcms/dotcli/#readme-examples) 节.
    -   有效的 CLI 工作空间应包含 `.dot-workspace` 在您的项目根中的文件。 请将文件输入您的仓库, 符合您工作空间的其他文件请查看 [工作空间](https://npmcn.com/package/%40dotcms/dotcli/#readme-workspace) 节.
    -   将更改提交到您的仓库 .
-   现在,如果整合成功,你应该看到在您的存储器中新承诺的反映在您dotCMS实例中.
    

以下是Git寄存器在GitHub Action集成后如何看起来的例子:

| 文件/目录 | 类型 | 说明 |
| --- | --- | --- |
| `.github/workflows/` | 目录 | GitHub 动作工作流程 |
| `content-types/` | 目录 | 内容 - 类型目录 |
| `files/` | 目录 | 文件目录 |
| `languages/` | 目录 | 语言目录 |
| `sites/` | 目录 | 站点目录 |
| `.dot-workspace.yml` | 文件 | CLI 工作空间标记 |
| `.gitignore` | 文件 | Git 文件排除 |
| `README.md` | 文件 | 项目读取器 |
| `.env` | 文件 | 按下命令选项光谱 |

-   GitHub 动作执行的默认命令是全局 `push`
-   Global Push有不同的选择. 控制命令执行的更多细节见 [全球推力](https://npmcn.com/package/%40dotcms/dotcli/cli/docs/push.adoc) 详细情况.
-   Global push 命令要求的任何其他选项可以在 `.env` 文件的格式如下: `DOT_CLI_OPTS="--option1 --option2"` 所以,一个有效的例子 一个 `.env` 文件可能像这样 `DOT_CLI_OPTS="--force --dry-run"`

```shell
   DOT_CLI_OPTS=" --removeAssets --removeFolders --removeSites --removeContentTypes --removeLanguages --errors"
```

这些选项可能造成数据丢失,因此谨慎使用. 这就是为什么它们不能被默认启用. 除非你们知道自己在做什么,否则,你们绝不允许他们发言.

## 常见问题

### @dotcms/dotcli 是什么？

管理dotCMS内容的官方命令行工具\.

### 如何安装 @dotcms/dotcli？

在项目目录运行 npm install @dotcms/dotcli，或使用 pnpm add / yarn add / bun add。

### @dotcms/dotcli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dotcms\_\_dotcli 是否存在。

### @dotcms/dotcli 可以商用吗？

@dotcms/dotcli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcms/dotcli 的下载量有多少？

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

### @dotcms/dotcli 还在维护吗？

最新版本 26\.11\.17-1 发布于 2026/11/18（今天）；至今共发布 1061 个版本，其中过去 12 个月发布了 452 个；首次发布于 2024/02/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

