enonic-sandbox-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Enonic CLI & Local Dev Environment Helper

Enonic CLI 与本地开发环境助手

Procedures

流程

Step 1: Detect Workspace Context

Execute
```
node scripts/find-enonic-targets.mjs
```
from the skill root to scan the current workspace for Enonic project markers (
```
.enonic
```
,
```
build.gradle
```
with
```
com.enonic.xp
```
plugin,
```
gradle.properties
```
with
```
xpVersion
```
).
If markers are found, note the project name, linked sandbox, and XP version from the output. Use these values as defaults for subsequent commands.
If no markers are found, treat the request as a greenfield setup and proceed to sandbox creation or project scaffolding as appropriate.

Step 2: Ensure CLI is Available

Verify the Enonic CLI is installed by running
```
enonic --version
```
.

If the command fails, read

references/cli-reference.md

for installation instructions and guide through the appropriate method for the detected OS:

npm (any OS):
```
npm install -g @enonic/cli
```

macOS:

brew tap enonic/cli && brew install --no-quarantine enonic

Linux:

wget -qO- https://repo.enonic.com/public/com/enonic/cli/installer/cli-linux/1.0.0/cli-linux-1.0.0.sh | sh

Windows:

scoop bucket add enonic https://github.com/enonic/cli-scoop.git && scoop install enonic

After installation, verify with
```
enonic --version
```
.

Step 3: Sandbox Management

Read
```
references/cli-reference.md
```
for the full sandbox command catalog.

Match the request to the correct operation:

Create:

enonic sandbox create <name> [-v <version>] [-t <template>] [--skip-template] [-f]

List:
```
enonic sandbox ls
```

Start:

enonic sandbox start <name> [--detach] [--prod] [--debug]

Stop:
```
enonic sandbox stop
```

Upgrade:

enonic sandbox upgrade <name> -v <version>

Delete:
```
enonic sandbox delete <name> -f
```
Copy:
```
enonic sandbox copy <source> <target>
```

When creating a sandbox, prompt for the XP version if not specified. Use
```
-f
```
flag for non-interactive execution when the version and name are known.
If the request mentions templates, list available templates or use
```
-t <template>
```
flag. Use
```
--skip-template
```
to create a bare sandbox with no pre-installed apps.

Step 4: Project Scaffolding

For new project creation, use the simplified command:

enonic create <name> [-r <starter>] [-s <sandbox>] [-f]

Common starters include

starter-vanilla

starter-headless

, and

starter-nextjs

. Read

references/cli-reference.md

for the full list of options.

To link an existing project to a different sandbox:
```
enonic project sandbox <name>
```
Ensure the project folder contains
```
build.gradle
```
and
```
.enonic
```
configuration after creation.

Step 5: Development Workflow

Determine the appropriate development command:
- Dev mode (hot-reload):
```
enonic dev
```
  — starts the sandbox in detached mode and runs the app with file watching. Execute from the project root.
- Build only:
```
enonic project build
```
- Deploy to sandbox:
```
enonic project deploy [sandbox-name] [-c]
```
  — use
```
-c
```
  for continuous deployment.
- Install to running XP:
```
enonic project install
```
- Run tests:
```
enonic project test
```
- Clean build artifacts:
```
enonic project clean
```
- Arbitrary Gradle task:
```
enonic project gradle <tasks>
```
If the sandbox is not running, start it first:
```
enonic sandbox start <name> -d
```
To terminate dev mode, use
```
Ctrl-C
```
. The CLI will attempt to stop the detached sandbox automatically.

Step 6: App Management on Running XP

For managing applications on a running XP instance, read
```
references/cli-reference.md
```
for the XP app commands.

Match the operation:

Install from URL:
```
enonic app install --url <jar-url>
```
Install from file:
```
enonic app install --file <path-to-jar>
```
Start app:
```
enonic app start <app-key>
```
Stop app:
```
enonic app stop <app-key>
```

Authentication is required for XP commands. Use
```
--cred-file <path>
```
(XP 7.15+) or set
```
ENONIC_CLI_REMOTE_USER
```
and
```
ENONIC_CLI_REMOTE_PASS
```
environment variables.

Step 7: CI/CD Pipeline Generation

Read
```
assets/enonic-ci.template.yml
```
for the GitHub Actions workflow template.
Customize the template based on the project:
- Set the correct XP version in the sandbox creation step.
- Set the app name and Gradle build parameters.
- Configure deployment targets (sandbox for staging, cloud for production).
Place the generated workflow file at
```
.github/workflows/enonic-ci.yml
```
in the project repository.

Step 8: Troubleshooting

If a sandbox fails to start or a deployment fails, read
```
references/troubleshooting.md
```
for common issues and resolutions.
Key diagnostic commands:
- ```
enonic sandbox ls
```
  — check sandbox status and XP version.
- ```
enonic system info
```
  — check running XP instance details.
- Check port
```
8080
```
  (HTTP) and
```
5005
```
  (debug) availability.
Read
```
references/compatibility.md
```
for CLI-to-XP version compatibility if version mismatch errors occur.

步骤1：检测工作区上下文

从skill根目录执行
```
node scripts/find-enonic-targets.mjs
```
，扫描当前工作区的Enonic项目标记（
```
.enonic
```
、引入了
```
com.enonic.xp
```
插件的
```
build.gradle
```
、包含
```
xpVersion
```
的
```
gradle.properties
```
）。
如果找到标记，从输出中记录项目名称、关联的沙箱和XP版本，将这些值作为后续命令的默认值。
如果未找到标记，将请求视为全新项目搭建，按需进入沙箱创建或项目脚手架搭建流程。

步骤2：确保CLI可用

运行
```
enonic --version
```
验证Enonic CLI是否已安装。

如果命令执行失败，读取

references/cli-reference.md

获取安装指引，根据检测到的操作系统选择合适的安装方法：

npm（全操作系统通用）：
```
npm install -g @enonic/cli
```

macOS：

brew tap enonic/cli && brew install --no-quarantine enonic

Linux：

wget -qO- https://repo.enonic.com/public/com/enonic/cli/installer/cli-linux/1.0.0/cli-linux-1.0.0.sh | sh

Windows：

scoop bucket add enonic https://github.com/enonic/cli-scoop.git && scoop install enonic

安装完成后，使用
```
enonic --version
```
验证安装结果。

步骤3：沙箱管理

读取
```
references/cli-reference.md
```
获取完整的沙箱命令列表。

匹配请求对应的正确操作：

创建：

enonic sandbox create <name> [-v <version>] [-t <template>] [--skip-template] [-f]

列出：
```
enonic sandbox ls
```

启动：

enonic sandbox start <name> [--detach] [--prod] [--debug]

停止：
```
enonic sandbox stop
```

升级：

enonic sandbox upgrade <name> -v <version>

删除：
```
enonic sandbox delete <name> -f
```
复制：
```
enonic sandbox copy <source> <target>
```

创建沙箱时，如果未指定XP版本则向用户询问。当版本和名称已知时，使用
```
-f
```
参数实现非交互式执行。
如果请求提到模板，列出可用模板或使用
```
-t <template>
```
参数。使用
```
--skip-template
```
创建没有预装应用的基础沙箱。

步骤4：项目脚手架搭建

创建新项目时使用简化命令：

enonic create <name> [-r <starter>] [-s <sandbox>] [-f]

常用启动模板包括

starter-vanilla

、

starter-headless

和

starter-nextjs

。读取

references/cli-reference.md

获取完整的选项列表。

将现有项目关联到其他沙箱的命令：
```
enonic project sandbox <name>
```
确保项目创建完成后，文件夹中包含
```
build.gradle
```
和
```
.enonic
```
配置文件。

步骤5：开发工作流

选择合适的开发命令：
- 开发模式（热重载）：
```
enonic dev
```
  — 以分离模式启动沙箱，运行应用并监听文件变动，在项目根目录执行该命令。
- 仅构建：
```
enonic project build
```
- 部署到沙箱：
```
enonic project deploy [sandbox-name] [-c]
```
  — 使用
```
-c
```
  参数开启持续部署。
- 安装到运行中的XP实例：
```
enonic project install
```
- 运行测试：
```
enonic project test
```
- 清理构建产物：
```
enonic project clean
```
- 执行任意Gradle任务：
```
enonic project gradle <tasks>
```
如果沙箱未运行，先启动沙箱：
```
enonic sandbox start <name> -d
```
终止开发模式使用
```
Ctrl-C
```
，CLI会自动尝试停止分离模式运行的沙箱。

步骤6：运行中XP实例的应用管理

管理运行中XP实例上的应用时，读取
```
references/cli-reference.md
```
获取XP应用命令。

匹配对应操作：

从URL安装：
```
enonic app install --url <jar-url>
```
从本地文件安装：
```
enonic app install --file <path-to-jar>
```
启动应用：
```
enonic app start <app-key>
```
停止应用：
```
enonic app stop <app-key>
```

XP命令需要身份验证，使用
```
--cred-file <path>
```
（XP 7.15+版本支持）或设置
```
ENONIC_CLI_REMOTE_USER
```
和
```
ENONIC_CLI_REMOTE_PASS
```
环境变量完成认证。

步骤7：CI/CD流水线生成

读取
```
assets/enonic-ci.template.yml
```
获取GitHub Actions工作流模板。
基于项目情况自定义模板：
- 在沙箱创建步骤设置正确的XP版本。
- 设置应用名称和Gradle构建参数。
- 配置部署目标（测试环境用沙箱，生产环境用云端）。
将生成的工作流文件存放在项目仓库的
```
.github/workflows/enonic-ci.yml
```
路径下。

步骤8：故障排查

如果沙箱启动失败或部署失败，读取
```
references/troubleshooting.md
```
获取常见问题和解决方案。
核心诊断命令：
- ```
enonic sandbox ls
```
  — 检查沙箱状态和XP版本。
- ```
enonic system info
```
  — 检查运行中XP实例的详细信息。
- 检查端口
```
8080
```
  （HTTP）和
```
5005
```
  （调试）的可用性。
如果出现版本不匹配错误，读取
```
references/compatibility.md
```
获取CLI与XP版本的兼容对应关系。

Error Handling

错误处理

If
```
scripts/find-enonic-targets.mjs
```
returns no results, proceed with greenfield setup instructions rather than failing.
If
```
enonic --version
```
fails, guide through CLI installation per Step 2 before proceeding.
If sandbox creation fails with a version error, read
```
references/compatibility.md
```
and suggest a compatible XP version.
If port conflicts occur during sandbox start, read
```
references/troubleshooting.md
```
for resolution steps.
If
```
enonic dev
```
fails, verify the project has a Gradle
```
dev
```
task (present in all official starters) and that the linked sandbox exists and is not already running in another terminal.

如果
```
scripts/find-enonic-targets.mjs
```
没有返回结果，按照全新项目搭建指引继续流程，不要直接报错。
如果
```
enonic --version
```
执行失败，先按照步骤2引导用户安装CLI，再继续后续操作。
如果沙箱创建因版本错误失败，读取
```
references/compatibility.md
```
并推荐兼容的XP版本。
如果沙箱启动时出现端口冲突，读取
```
references/troubleshooting.md
```
获取解决步骤。
如果
```
enonic dev
```
执行失败，验证项目是否包含Gradle
```
dev
```
任务（所有官方启动模板都自带该任务），以及关联的沙箱是否存在、是否已在其他终端运行。