Back to Details

aem-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AEM CLI

AEM CLI

Local development tool for AEM Edge Delivery Services. Three commands: 
aem up
(local dev server), 
aem import
(import server + UI), 
aem content
(da.live content sync).
Binary: 
aem
(primary), 
hlx
(alias from the former 
helix-cli
package, renamed to 
@adobe/aem-cli
at v15.0.0).
AEM Edge Delivery Services的本地开发工具。包含三个命令：
aem up
（本地开发服务器）、
aem import
（导入服务器+界面）、
aem content
（与da.live的内容同步）。
可执行文件：
aem
（主命令）、
hlx
（原
helix-cli
包的别名，在v15.0.0版本时更名为
@adobe/aem-cli
）。

1. Install

1. 安装

Prerequisite: Node.js 12.11 or newer (Node 22 LTS recommended). 
[verified]
bash
undefined
前提条件： Node.js 12.11或更高版本（推荐使用Node 22 LTS）。
[verified]
bash
undefined

Global install

全局安装

npm install -g @adobe/aem-cli
npm install -g @adobe/aem-cli

One-off via npx (no global install needed)

通过npx一次性使用（无需全局安装）

npx -y @adobe/aem-cli up

**Verify:**
```bash
aem --version   # or: hlx --version
npx -y @adobe/aem-cli up

**验证安装：**
```bash
aem --version   # 或：hlx --version

Migrating from the old helix-cli package

从旧版helix-cli包迁移

If 
npm install -g @adobe/aem-cli
fails with 
File exists: …/hlx
, the old package is still installed and owns the binary. Uninstall it first (npm package scoped under 
@adobe
, named 
helix-cli
): 
[verified]
bash
npm uninstall -g @adobe/helix-cli
npm install -g @adobe/aem-cli
The binary name changes from 
hlx
to 
aem
; both work after installation because 
aem-cli
ships 
hlx
as an alias.
如果执行
npm install -g @adobe/aem-cli
时提示
File exists: …/hlx
，说明旧版包仍在安装中并占用了该可执行文件。请先卸载旧版包（npm包范围为
@adobe
，包名为
helix-cli
）：
[verified]
bash
npm uninstall -g @adobe/helix-cli
npm install -g @adobe/aem-cli
可执行文件名称从
hlx
变更为
aem
；安装完成后两者均可使用，因为
aem-cli
附带了
hlx
作为别名。

2. 
aem up
— Local Dev Server

2. 
aem up
—— 本地开发服务器

Agent-standard invocation:
bash
aem up --no-open --forward-browser-logs
Check the server is running:
bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
标准调用方式：
bash
aem up --no-open --forward-browser-logs
检查服务器是否运行：
bash
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000

Expected: 200

预期结果：200

undefined
undefined

Key flags

关键参数

FlagWhat it does
--no-open
Do not open a browser window on startup
--forward-browser-logs
Forward browser console messages (log, error, warn, info) to the terminal
--port <n>
Listen on a different port (default: 
3000
)
--addr <addr>
Bind address; use 
*
to allow external connections (default: 
127.0.0.1
)
--url <url>
Origin URL to proxy content from (overrides the project's default pages URL)
--html-folder <dir>
Serve local HTML files from 
<dir>
without extensions
--html-mount <path>
URL path where 
--html-folder
files are served (default: 
/<dir>
)
--no-livereload
Disable automatic browser reload on file changes
--stop-other
Stop another AEM CLI instance on the same port before starting (default: true)
--tls-cert <file>
Path to 
.pem
file for TLS (see §4)
--tls-key <file>
Path to 
.key
file for TLS (see §4)
--allow-insecure
Allow insecure (self-signed cert) requests to the upstream server
--print-index
Print indexed records for the current page (debugging)
--site-token <token>
Site token for CLI access to the website
--cookies
Proxy all cookies (default: only 
hlx-auth-token
is proxied)
--html-folder
: without it, local HTML files are never served — all requests proxy to the remote pipeline, returning 404 for local-only paths. 
[verified]
参数功能
--no-open
启动时不打开浏览器窗口
--forward-browser-logs
将浏览器控制台消息（log、error、warn、info）转发到终端
--port <n>
使用指定端口监听（默认：
3000
）
--addr <addr>
绑定地址；使用
*
允许外部连接（默认：
127.0.0.1
）
--url <url>
用于代理内容的源URL（覆盖项目默认的页面URL）
--html-folder <dir>
从
<dir>
目录提供本地HTML文件，无需扩展名
--html-mount <path>
--html-folder
中文件的服务URL路径（默认：
/<dir>
）
--no-livereload
禁用文件变更时的自动浏览器重载
--stop-other
启动前停止同一端口上的其他AEM CLI实例（默认：true）
--tls-cert <file>
TLS证书的
.pem
文件路径（见第4节）
--tls-key <file>
TLS密钥的
.key
文件路径（见第4节）
--allow-insecure
允许向上游服务器发送不安全（自签名证书）请求
--print-index
打印当前页面的索引记录（用于调试）
--site-token <token>
CLI访问网站的站点令牌
--cookies
代理所有Cookie（默认：仅代理
hlx-auth-token
）
--html-folder
： 如果不设置该参数，本地HTML文件将不会被提供——所有请求都会代理到远程流水线，仅本地存在的路径会返回404。
[verified]

Serving import HTML locally (preview-import pattern)

本地提供导入的HTML文件（预览导入模式）

bash
aem up --html-folder drafts --no-open --forward-browser-logs
bash
aem up --html-folder drafts --no-open --forward-browser-logs

Files in ./drafts/ are served at /drafts/<name> (no extension needed)

./drafts/目录下的文件会在/drafts/<name>路径下提供（无需扩展名）


---

---

3. 
.env
Configuration

3. 
.env
配置

All options can be persisted in 
.env
at the project root; loaded automatically. 
[verified]
dotenv
undefined
所有选项均可持久化到项目根目录的
.env
文件中，会自动加载。
[verified]
dotenv
undefined

.env example

.env示例

AEM_PORT=8080 AEM_PAGES_URL=https://stage.myproject.com AEM_FORWARD_BROWSER_LOGS=true AEM_HTML_FOLDER=drafts AEM_TLS_CERT=server.crt AEM_TLS_KEY=server.key AEM_OPEN=/products

See [references/command-reference.md](./references/command-reference.md) for the complete
`AEM_*` environment variable reference with defaults.

---
AEM_PORT=8080 AEM_PAGES_URL=https://stage.myproject.com AEM_FORWARD_BROWSER_LOGS=true AEM_HTML_FOLDER=drafts AEM_TLS_CERT=server.crt AEM_TLS_KEY=server.key AEM_OPEN=/products

完整的`AEM_*`环境变量参考及默认值，请查看[references/command-reference.md](./references/command-reference.md)。

---

4. HTTPS / TLS

4. HTTPS / TLS

Trusted local certificate (recommended — avoids browser warnings)

受信任的本地证书（推荐——避免浏览器警告）

Install 
mkcert
(
brew install mkcert
on macOS, 
choco install mkcert
on Windows, 
go install filippo.io/mkcert@latest
elsewhere), then:
bash
mkcert -install                                          # one-time CA install
mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1
aem up --tls-cert server.crt --tls-key server.key
安装
mkcert
（macOS使用
brew install mkcert
，Windows使用
choco install mkcert
，其他平台使用
go install filippo.io/mkcert@latest
），然后执行：
bash
mkcert -install                                          # 一次性安装CA证书
mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1
aem up --tls-cert server.crt --tls-key server.key

Self-signed certificate (no mkcert)

自签名证书（无需mkcert）

bash
openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes \
  -out server.crt -keyout server.key -subj "/CN=localhost"
aem up --tls-cert server.crt --tls-key server.key
bash
openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes \
  -out server.crt -keyout server.key -subj "/CN=localhost"
aem up --tls-cert server.crt --tls-key server.key

Persisting TLS in .env

在.env中持久化TLS配置

dotenv
AEM_TLS_CERT=server.crt
AEM_TLS_KEY=server.key
dotenv
AEM_TLS_CERT=server.crt
AEM_TLS_KEY=server.key

5. Corporate Proxy and Certificate Trust

5. 企业代理与证书信任

aem up
fails with 
unable to get local issuer certificate
behind HTTPS-intercepting proxies. Export the corporate CA cert from your browser or ask IT, then set:
bash
undefined
在启用HTTPS拦截的代理环境下，
aem up
会报错
unable to get local issuer certificate
。从浏览器导出企业CA证书或向IT部门获取，然后设置：
bash
undefined

macOS / Linux

macOS / Linux

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt aem up
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt aem up

Windows

Windows

set NODE_EXTRA_CA_CERTS=./certs/corporate-ca.pem aem up

`NODE_EXTRA_CA_CERTS` is a Node built-in — set it in the shell profile or CI, not `.env`.

**Proxy env vars:**

| Variable | Purpose |
|---|---|
| `HTTP_PROXY` | Proxy for HTTP requests |
| `HTTPS_PROXY` | Proxy for HTTPS requests |
| `ALL_PROXY` | Fallback for either protocol |
| `NO_PROXY` | Comma-separated hosts to bypass; `*` disables all proxies |

---
set NODE_EXTRA_CA_CERTS=./certs/corporate-ca.pem aem up

`NODE_EXTRA_CA_CERTS`是Node的内置变量——请在shell配置文件或CI中设置，不要在`.env`中设置。

**代理环境变量：**

| 变量 | 用途 |
|---|---|
| `HTTP_PROXY` | HTTP请求的代理 |
| `HTTPS_PROXY` | HTTPS请求的代理 |
| `ALL_PROXY` | 两种协议的备用代理 |
| `NO_PROXY` | 逗号分隔的需绕过代理的主机列表；`*`表示禁用所有代理 |

---

6. 
aem import
— Import Server

6. 
aem import
—— 导入服务器

Local import server (default port 3001) serving the helix-importer-ui.
bash
aem import                   # opens Importer UI in browser at port 3001
aem import --no-open         # headless / background start
aem import --port 3002       # different port
Key flags:
FlagDefaultWhat it does
--port
3001
Import server port
--no-open
—Do not open the browser window
--allow-insecure
true
Allow self-signed certs on the proxied site
--ui-repo <url>
helix-importer-ui repo on GitHubCustom Importer UI repo
--skip-ui
false
Skip downloading/installing the UI
--headers-file <file>
—JSON file of custom headers for proxy requests
--cache <dir>
—Cache proxied responses to a local folder
--dump-headers
false
Print request headers to console for debugging
--tls-cert
/ 
--tls-key
—TLS for the import server itself (see §4)
Workflow: For writing the 
import.js
transformation script or running the full import pipeline, use the page-import or generate-import-html skills. This skill covers only starting and configuring the server.
本地导入服务器（默认端口3001），用于提供helix-importer-ui界面。
bash
aem import                   # 在浏览器打开端口3001的导入界面
aem import --no-open         # 无头/后台启动
aem import --port 3002       # 使用其他端口
关键参数：
参数默认值功能
--port
3001
导入服务器端口
--no-open
—不打开浏览器窗口
--allow-insecure
true
允许代理站点使用自签名证书
--ui-repo <url>
GitHub上的helix-importer-ui仓库自定义导入界面仓库
--skip-ui
false
跳过下载/安装界面
--headers-file <file>
—代理请求的自定义头信息JSON文件
--cache <dir>
—将代理响应缓存到本地目录
--dump-headers
false
将请求头打印到控制台用于调试
--tls-cert
/ 
--tls-key
—导入服务器自身的TLS配置（见第4节）
工作流： 若要编写
import.js
转换脚本或运行完整的导入流水线，请使用page-import或generate-import-html技能。本技能仅涵盖服务器的启动与配置。

7. 
aem content
— da.live Content Sync

7. 
aem content
—— da.live内容同步

bash
aem content clone [--path /]   # auth via browser popup; clones into ./content/
aem content status             # show added / modified / deleted files
aem content diff [path]        # diff local vs remote
aem content merge [path]       # sync remote changes into local files
aem content add <files..>      # stage changes (like git add)
aem content commit -m "..."    # commit staged changes (like git commit)
aem content push               # upload committed changes to da.live
aem content push --force       # overwrite remote on conflict
Auth token cached at 
.hlx/.da-token.json
(gitignored); browser OAuth on first use.
Read the token directly to authenticate curl calls:
bash
TOKEN=$(jq -r .access_token .hlx/.da-token.json)
bash
aem content clone [--path /]   # 通过浏览器弹窗认证；克隆到./content/目录
aem content status             # 显示已添加/修改/删除的文件
aem content diff [path]        # 对比本地与远程文件差异
aem content merge [path]       # 将远程变更同步到本地文件
aem content add <files..>      # 暂存变更（类似git add）
aem content commit -m "..."    # 提交暂存的变更（类似git commit）
aem content push               # 将提交的变更上传到da.live
aem content push --force       # 冲突时覆盖远程内容
认证令牌缓存于
.hlx/.da-token.json
（已加入git忽略）；首次使用时通过浏览器OAuth认证。
可直接读取令牌以认证curl请求：
bash
TOKEN=$(jq -r .access_token .hlx/.da-token.json)

Known behaviour: binary files

已知特性：二进制文件

aem content push
silently no-ops on binary files (images, PDFs, fonts). 
[verified]
Verify a binary upload landed:
bash
curl -sI https://content.da.live/<org>/<repo>/path/to/image.png | grep -i "content-type"
If it 404s, upload the binary directly via the DA Source API:
bash
TOKEN=$(jq -r .access_token .hlx/.da-token.json)
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @./image.png \
  "https://admin.da.live/source/<org>/<repo>/path/to/image.png"
aem content push
会静默跳过二进制文件（图片、PDF、字体）。
[verified]
验证二进制文件是否上传成功：
bash
curl -sI https://content.da.live/<org>/<repo>/path/to/image.png | grep -i "content-type"
如果返回404，请通过DA Source API直接上传二进制文件：
bash
TOKEN=$(jq -r .access_token .hlx/.da-token.json)
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @./image.png \
  "https://admin.da.live/source/<org>/<repo>/path/to/image.png"

Known behaviour: pre-upload HTML normalization

已知特性：上传前HTML标准化

Pre-upload normalization strips EDS icon decorations (
<span class="icon icon-X">
etc.). 
[verified]
For byte-faithful EDS HTML, POST directly to the DA Source API:
bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary @./page.html \
  "https://admin.da.live/source/<org>/<repo>/path/to/page.html"
See the da-content skill (platform reference §7) for the DA Source API contract and rate limits.
上传前的标准化处理会移除EDS图标装饰（如
<span class="icon icon-X">
等）。
[verified]
若要实现字节级一致的EDS HTML上传，请直接POST到DA Source API：
bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/html" \
  --data-binary @./page.html \
  "https://admin.da.live/source/<org>/<repo>/path/to/page.html"
DA Source API协议及速率限制，请查看da-content技能（平台参考第7节）。

Troubleshooting

故障排查

SymptomCauseFix
npm install -g @adobe/aem-cli
→ 
File exists: …/hlx
old 
helix-cli
package still owns the binary		uninstall the old package (see §1) then reinstall
aem up
→ 
EADDRINUSE: address already in use :::3000
Port 3000 is takenPass 
--port <other>
or kill the process on 3000
aem up
→ 
unable to get local issuer certificate
Corporate proxy intercepts TLSExport corp CA cert → 
export NODE_EXTRA_CA_CERTS=/path/to/ca.crt
localhost:3000/mypath
returns 404		Local HTML file in 
mypath/
not mounted		Add 
--html-folder mypath
(or 
AEM_HTML_FOLDER=mypath
in 
.env
)
aem up
→ pipeline 404 for pages that exist live		Wrong origin URL proxiedPass 
--url https://your-pages-url.aem.page
aem content push
reports success but binary is missing		CLI silently no-ops on binariesUpload binary via DA Source API (see §7)
aem content push
strips icon spans from HTML		Pre-upload normalization removes EDS decorationsPOST directly to DA Source API for byte-faithful upload
aem import
UI doesn't load		Port 3001 in use, or UI download failedTry 
--port 3002
; or 
--skip-ui
and open the UI separately
症状原因解决方法
npm install -g @adobe/aem-cli
→ 
File exists: …/hlx
旧版
helix-cli
包仍占用可执行文件		先卸载旧版包（见第1节），然后重新安装
aem up
→ 
EADDRINUSE: address already in use :::3000
端口3000被占用使用
--port <其他端口>
参数，或终止占用3000端口的进程
aem up
→ 
unable to get local issuer certificate
企业代理拦截了TLS导出企业CA证书 → 设置
export NODE_EXTRA_CA_CERTS=/path/to/ca.crt
localhost:3000/mypath
返回404		本地
mypath/
目录下的HTML文件未挂载		添加
--html-folder mypath
参数（或在
.env
中设置
AEM_HTML_FOLDER=mypath
）
aem up
→ 线上存在的页面返回流水线404		代理了错误的源URL使用
--url https://your-pages-url.aem.page
参数
aem content push
显示成功但二进制文件缺失		CLI会静默跳过二进制文件通过DA Source API上传二进制文件（见第7节）
aem content push
移除了HTML中的图标span标签		上传前的标准化处理移除了EDS装饰直接POST到DA Source API以实现字节级一致的上传
aem import
界面无法加载		端口3001被占用，或界面下载失败尝试使用
--port 3002
参数；或使用
--skip-ui
参数并单独打开界面

Reference

参考资料

  • references/command-reference.md — exhaustive flag + 
    AEM_*
    env-var tables for all commands
  • Upstream docs: https://www.npmjs.com/package/@adobe/aem-cli — npm page for 
    @adobe/aem-cli
    (the GitHub repo is named 
    helix-cli
    for historical reasons)
  • Importer UI: the helix-importer-ui (search npm or GitHub for 
    helix-importer-ui
    ) — served by 
    aem import
  • references/command-reference.md —— 所有命令的详尽参数及
    AEM_*
    环境变量表格
  • 上游文档：https://www.npmjs.com/package/@adobe/aem-cli —— 
    @adobe/aem-cli
    的npm页面（GitHub仓库因历史原因仍命名为
    helix-cli
    ）
  • 导入界面：helix-importer-ui（在npm或GitHub搜索
    helix-importer-ui
    ）—— 由
    aem import
    提供服务