＋ Add to collection

Or: paste this in your AI chat

Please install the Agent Skill "adobe/aem-cli" for me from skillmd.com. A SkillMD skill is a SKILL.md file — plain markdown plus a few companion files — that you save into my skills directory. Use whichever fetch route fits your setup: (1) if you have a terminal, run npx -y skillmds add adobe/aem-cli; (2) otherwise fetch the file manifest at https://api.skillmd.com/api/skills/adobe/aem-cli/bundle?format=manifest and download each listed file from its "url" into aem-cli/ in your skills directory; (3) if the SkillMD MCP tools are connected, call skillmd_download with slug "adobe/aem-cli" and save the returned files under aem-cli/. Show me the SKILL.md before saving if you'd like me to review it. If your skills directory is read-only (e.g. the Claude desktop app), save the files to a working folder instead and tell me — I'll add them through my app's skills settings.

README badge

Show this skill's registry status in your repo:

[![SkillMD](https://skillmd.com/badge/adobe/aem-cli.svg)](https://skillmd.com/skills/adobe/aem-cli)

Aem CLI

Name: Aem CLI
Rating: 4.5 (4 reviews)
Author: Adobe

by Adobe adobe/aem-cli multi-file Updated Jul 6, 2026

Install, configure, and troubleshoot the Adobe AEM CLI (@adobe/aem-cli) for local Edge Delivery development, including dev server, import server, content sync, TLS, and proxy setup.

SKILL.md

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).

1. Install

Prerequisite: Node.js 12.11 or newer (Node 22 LTS recommended). [verified]

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

# One-off via npx (no global install needed)
npx -y @adobe/aem-cli up

Verify:

aem --version   # or: hlx --version

Migrating from the old helix-cli package

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]

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.

2. `aem up` — Local Dev Server

Agent-standard invocation:

aem up --no-open --forward-browser-logs

Check the server is running:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Expected: 200

Key flags

Flag	What 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]

Serving import HTML locally (preview-import pattern)

aem up --html-folder drafts --no-open --forward-browser-logs
# Files in ./drafts/ are served at /drafts/<name> (no extension needed)

3. `.env` Configuration

All options can be persisted in .env at the project root; loaded automatically. [verified]

# .env example
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 for the complete AEM_* environment variable reference with defaults.

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:

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

Self-signed certificate (no mkcert)

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

AEM_TLS_CERT=server.crt
AEM_TLS_KEY=server.key

5. Corporate Proxy and Certificate Trust

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:

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

# 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

6. `aem import` — Import Server

Local import server (default port 3001) serving the helix-importer-ui.

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:

Flag	Default	What 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 GitHub	Custom 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.

7. `aem content` — da.live Content Sync

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:

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:

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:

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

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:

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.

Troubleshooting

Symptom	Cause	Fix
`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 taken	Pass `--port <other>` or kill the process on 3000
`aem up` → `unable to get local issuer certificate`	Corporate proxy intercepts TLS	Export 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 proxied	Pass `--url https://your-pages-url.aem.page`
`aem content push` reports success but binary is missing	CLI silently no-ops on binaries	Upload binary via DA Source API (see §7)
`aem content push` strips icon spans from HTML	Pre-upload normalization removes EDS decorations	POST directly to DA Source API for byte-faithful upload
`aem import` UI doesn't load	Port 3001 in use, or UI download failed	Try `--port 3002`; or `--skip-ui` and open the UI separately

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

---
name: aem-cli
description: Install, configure, and troubleshoot the Adobe AEM CLI (@adobe/aem-cli) for local Edge Delivery development, including dev server, import server, content sync, TLS, and proxy setup.
license: Apache-2.0
---

# 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).

---

## 1. Install

**Prerequisite:** Node.js 12.11 or newer (Node 22 LTS recommended). `[verified]`

```bash
# Global install
npm install -g @adobe/aem-cli

# One-off via npx (no global install needed)
npx -y @adobe/aem-cli up
```

**Verify:**
```bash
aem --version   # or: hlx --version
```

### Migrating from the old helix-cli package

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.

---

## 2. `aem up` — Local Dev Server

**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
# Expected: 200
```

### Key flags

| Flag | What 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]`

### Serving import HTML locally (preview-import pattern)

```bash
aem up --html-folder drafts --no-open --forward-browser-logs
# Files in ./drafts/ are served at /drafts/<name> (no extension needed)
```

---

## 3. `.env` Configuration

All options can be persisted in `.env` at the project root; loaded automatically. `[verified]`

```dotenv
# .env example
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.

---

## 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
```

### Self-signed certificate (no 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
```

### Persisting TLS in .env

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

---

## 5. Corporate Proxy and Certificate Trust

`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
# macOS / Linux
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt
aem up

# 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 |

---

## 6. `aem import` — Import Server

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:**

| Flag | Default | What 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 GitHub | Custom 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.

---

## 7. `aem content` — da.live Content Sync

```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)
```

### 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"
```

### Known behaviour: pre-upload HTML normalization

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.

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `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 taken | Pass `--port <other>` or kill the process on 3000 |
| `aem up` → `unable to get local issuer certificate` | Corporate proxy intercepts TLS | Export 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 proxied | Pass `--url https://your-pages-url.aem.page` |
| `aem content push` reports success but binary is missing | CLI silently no-ops on binaries | Upload binary via DA Source API (see §7) |
| `aem content push` strips icon spans from HTML | Pre-upload normalization removes EDS decorations | POST directly to DA Source API for byte-faithful upload |
| `aem import` UI doesn't load | Port 3001 in use, or UI download failed | Try `--port 3002`; or `--skip-ui` and open the UI separately |

---

## Reference

- [references/command-reference.md](./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`

adobe/skills/tree/main/plugins/aem/edge-delivery-services/skills/aem-cli commit · d21d4cbf66

▌
Rollout · adobe bundle
Deploy an entire redesigned site to AEM Edge Delivery Services by inventorying migrated pages, deduplicating blocks, and driving per-page deployment with tracking and verification.

142
repo stars
▌
Content Driven Development · adobe bundle
Orchestrate a content-driven development workflow for AEM Edge Delivery Services, ensuring code is built against real content with author-friendly content models.

142
repo stars
▌
Vercel Optimize · vercel-labs bundle
Audits Vercel projects for cost and performance optimization by collecting metrics, scanning code, and producing ranked recommendations grounded in data.

28.7k
repo stars
▌
Eas Hosting · expo bundle
Deploy Expo web apps and API routes to EAS Hosting (Cloudflare Workers), including export, deployment, environment secrets, custom domains, and authoring API routes with HTTP methods, CORS, and error handling.

2.2k
repo stars
▌
Cloudflare Deploy · openai bundle
Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services.

23.3k
repo stars
▌
Rpk · redpanda-data bundle
Install the rpk CLI on macOS, Linux, or Docker, and configure profiles, connection settings, SASL/TLS credentials, and Enterprise licenses for Redpanda clusters.

6
repo stars

Frequently asked questions

How do I install the Aem CLI skill?

Run npx skillmds add adobe/aem-cli in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Aem CLI skill do?

Install, configure, and troubleshoot the Adobe AEM CLI (@adobe/aem-cli) for local Edge Delivery development, including dev server, import server, content sync, TLS, and proxy setup. It is listed under DevOps & Infra, Web & Frontend, Cloud Platforms, Deployment & Release on SkillMD.

Is Aem CLI safe to use?

SkillMD's automated safety review verdict for this skill is CAUTION. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Aem CLI?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Aem CLI free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published Aem CLI?

Adobe (@adobe) published this skill as a verified publisher. Their other Agent Skills are listed on their SkillMD profile.