AEM Command Line Interface (`aem`)

Status

![codecov](https://codecov.io/gh/adobe/helix-cli)
!GitHub Actions Workflow Status
![GitHub license](https://github.com/adobe/helix-cli/blob/master/LICENSE.txt)
![GitHub issues](https://github.com/adobe/helix-cli/issues)

The AEM Command Line Interface allows web developers to create, develop, and deploy digital experiences using the Adobe Experience Manager Sites feature Edge Delivery Services. Some of this functionality was known as Franklin or Project Helix before.

Installation

Install aem as a global command. You need Node 12.11 or newer.

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

If this fails with File exists: /opt/homebrew/bin/hlx, please see here.

`Quick Start`

`$ aem --help Usage: aem [options]

Commands: aem up Run a AEM development server aem import Run the AEM import server

Options: --version Show version number [boolean] --log-file, --logFile Log file (use "-" for stdout) [array] [default: "-"] --log-level, --logLevel Log level [string] [choices: "silly", "debug", "verbose", "info", "warn", "error"] [default: "info"] --tls-key, --tlsKey Path to .key file (for enabling TLS) [string] --tls-cert, --tlsCert Path to .pem file (for enabling TLS) [string] --help Show help [boolean]

use --help to get command specific details.

for more information, find our manual at https://github.com/adobe/helix-cli`

`Starting development`

`$ cd $ aem up`

`$3`

The --open argument takes a path, eg --open=/products/, will cause the browser to be openend at the specific location. Disable with--no-open'.

`$3`

The --forward-browser-logs flag enables forwarding of browser console messages (log, error, warn, info) to the terminal. This is particularly useful for debugging client-side issues without having to open the browser's developer tools.

`$ aem up --forward-browser-logs`

When enabled, browser console messages will appear in your terminal with the following format:`[Browser:error] 2025-07-27T10:30:45.123Z http://localhost:3000/script.js:42 Error message here`

This feature is especially helpful when: - Debugging JavaScript errors in a headless environment - Monitoring client-side behavior during development - Working with AI coding assistants that need visibility into both server and client logs

`$3`

The --html-folder option enables serving HTML files without extensions, useful for previewing content changes when you don't have access to the authoring system.

`$ aem up --html-folder content`

This enables two features:

1. Extension-less URLs: Access /content/page to serve content/page.html2. Plain HTML with metadata: Createcontent/page.plain.html files that are automatically wrapped with proper HTML structure and metadata processing

#### Plain HTML files (.plain.html)

Plain HTML files contain only the main content and an optional metadata block. The CLI automatically: - Wraps content in

 structure
- Merges in

head.html

 content
- The metadata block is removed from the rendered content and converted to meta tags in the

.
$3
1. create the certificate

`$ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out server.crt -keyout server.key -subj "/CN=localhost"`

this will create 2 files: server.crt and server.key

Alternatively, if your browser does not trust the certificate, you can use mkcert to generate a trusted certificate:`bash

`Install mkcert via Homebrew or your preferred method, then run:`


mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1


2. start aem with tls support

`$ aem up --tls-cert server.crt --tls-key server.key ___ ________ ___ __ __ v14.26.1 / | / ____/ |/ / _____(_)___ ___ __ __/ /___ _/ /_____ _____ / /| | / __/ / /|_/ / / ___/ / ____ \/ / / / / __ / __/ __ \/ ___/ / ___ |/ /___/ / / / (__ ) / / / / / / /_/ / / /_/ / /_/ /_/ / / /_/ |_/_____/_/ /_/ /____/_/_/ /_/ /_/\__,_/_/\__,_/\__/\____/_/

info: Starting AEM dev server v14.26.1 info: Local AEM dev server up and running: https://localhost:3000/`

3. (optional) Add arguments to .env file:

`$ echo -e "AEM_TLS_CERT=server.crt\nAEM_TLS_KEY=server.key" >> .env`

`$3`

All the command arguments can also be specified via environment variables. the .envfile is loaded automatically.

example:

.env`dotenv AEM_OPEN=/products AEM_PORT=8080 AEM_PAGES_URL=https://stage.myproject.com`

#### HTTP Proxy

In order to use a HTTP proxy (eg behind a corporate firewall), you can set the respective environment variables:

NO_PROXY is a list of host names (optionally with a port). If the input URL matches any of the entries in NO_PROXY, then the input URL should be fetched by a direct request (i.e. without a proxy).

Matching follows the following rules:

NO_PROXY=*disables all proxies. Space and commas may be used to separate the entries in theNO_PROXYlist. IfNO_PROXYdoes not contain any entries, then proxies are never disabled. If a port is added after the host name, then the ports must match. If the URL does not have an explicit port name, the protocol's default port is used. Generally, the proxy is only disabled if the host name is an exact match for an entry in theNO_PROXYlist. The only exceptions are entries that start with a dot or with a wildcard; then the proxy is disabled if the host name ends with the entry. See test.js for examples of what should match and what does not.

*_PROXYThe environment variable used for the proxy depends on the protocol of the URL. For example, https://example.com uses the "https" protocol, and therefore the proxy to be used isHTTPS_PROXY (NOT HTTP_PROXY, which is only used for http:-URLs).

If present, ALL_PROXY is used as fallback if there is no other match.

#### Global

| option | variable | default | description | |--------|----------|---------|-------------| |--log-file | AEM_LOG_FILE | - | Log file. use -to log to stdout | |--log-level | AEM_LOG_LEVEL | info | Log level |

#### Up command

| option | variable | default | description | |-------------------|---------------------|-------------|-------------------------------------------------------------| |--port | AEM_PORT | 3000| Development server port | |--addr | AEM_ADDR | 127.0.0.1| Development server bind address | |--livereload | AEM_LIVERELOAD | true| Enable automatic reloading of modified sources in browser. | |--no-livereload | AEM_NO_LIVERELOAD | false| Disable live-reload. | |--forward-browser-logs | AEM_FORWARD_BROWSER_LOGS | false| Forward browser console logs to terminal. | |--html-folder | AEM_HTML_FOLDER| undefined | Serve HTML files from folder without extensions. Supports .html and .plain.html files. | |--open | AEM_OPEN | /| Open a browser window at specified path after server start. | |--no-open | AEM_NO_OPEN | false| Disable automatic opening of browser window. | |--tls-key | AEM_TLS_KEY| undefined | Path to .key file (for enabling TLS) | |--tls-cert | AEM_TLS_CERT | undefined | Path to .pem file (for enabling TLS) |

`Starting an import`

The AEM Importer is an application that supports importing content to AEM.

`$ cd $ aem import`

Read the full AEM Importer documentation.

`Developing AEM CLI`

`Testing`

You can use npm run checkto run the tests and check whether your code adheres to the aem-cli coding style.

`$3`

Browser-injected scripts (LiveReload and console log forwarding) are maintained in a separate sub-project at packages/browser-injectables/. This isolation keeps browser testing dependencies separate from the main CLI.

#### Development - Injectable scripts are inpackages/browser-injectables/src/- No build step required - scripts are used directly - Browser tests run only when injectable code changes

#### Testing Browser Injectables`bash cd packages/browser-injectables npm install npm test`

`Troubleshooting`

aem up `fails with` unable to get local issuer certificate

This error occurs when the server certificate is not trusted by Node.js. The typical cause is that connections to the server.aem.page and .hlx.pageare intercepted by an enterprise proxy or firewall which is trying to inspect the traffic.

These proxies use a private certificate authority (CA) to sign the certificates of the servers they intercept. To make Node.js trust the server certificate, you need to add the CA certificate to the list of trusted CAs.

`$3`

The CA certificate is typically provided by your IT department. You can ask them for the CA certificate and save it to a file, e.g.my-ca.crt.

Then you can use the NODE_EXTRA_CA_CERTSenvironment variable to make Node.js trust the CA certificate:

`bash export NODE_EXTRA_CA_CERTS=my-ca.crt aem up`

`$3`

If you don't have access to the CA certificate from your IT department, you can extract it directly from your browser:

1. Access the AEM admin URL in your browser (e.g., https://admin.hlx.page/sidekick/owner-name/repo-name/github-branch-name/config.json) 2. Click on the padlock icon in the address bar and view the certificate details 3. Export the certificate chain as a Base64 encoded.pemfile 4. Save it to a directory (e.g.,certs/hlx.page.pem) 5. Set the environment variable and run aem:

`bash export NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem aem up`

On Windows, use set instead of export:`cmd set NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem aem up`

Either approach will make Node.js trust the server certificate and aem up should work.

npm install `fails with` File exists: /opt/homebrew/bin/hlx

If you try to install @adobe/aem-cli:

`> npm install -g @adobe/aem-cli ... npm error EEXIST: file already exists npm error File exists: /opt/homebrew/bin/hlx npm error Remove the existing file and try again, or run npm`

This can happen when you previously had installed this tool under its old package name @adobe/helix-cli. Starting with version 15.0.0, this tool was renamed aem and published as @adobe/aem-cli. The previous @adobe/helix-cli has been deprecated. However, the new package still provides the command line binary under the old name hlx in addition to aem, for backwards compatibility, which can lead to the npm install error.

To solve, first uninstall the old version, then install again with the new name:

`npm uninstall -g @adobe/helix-cli npm install -g @adobe/aem-cli``

AEM Command Line Interface (`aem`)

Status

Installation

Install aem as a global command. You need Node 12.11 or newer.

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

If this fails with File exists: /opt/homebrew/bin/hlx, please see here.

`Quick Start`

`$ aem --help Usage: aem [options]

Commands: aem up Run a AEM development server aem import Run the AEM import server

use --help to get command specific details.

for more information, find our manual at https://github.com/adobe/helix-cli`

`Starting development`

`$ cd $ aem up`

`$3`

The --open argument takes a path, eg --open=/products/, will cause the browser to be openend at the specific location. Disable with--no-open'.

`$3`

`$ aem up --forward-browser-logs`

When enabled, browser console messages will appear in your terminal with the following format:`[Browser:error] 2025-07-27T10:30:45.123Z http://localhost:3000/script.js:42 Error message here`

`$3`

The --html-folder option enables serving HTML files without extensions, useful for previewing content changes when you don't have access to the authoring system.

`$ aem up --html-folder content`

This enables two features:

#### Plain HTML files (.plain.html)

Plain HTML files contain only the main content and an optional metadata block. The CLI automatically: - Wraps content in

 structure
- Merges in

head.html

 content
- The metadata block is removed from the rendered content and converted to meta tags in the

.
$3
1. create the certificate

`$ openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out server.crt -keyout server.key -subj "/CN=localhost"`

this will create 2 files: server.crt and server.key

Alternatively, if your browser does not trust the certificate, you can use mkcert to generate a trusted certificate:`bash

`Install mkcert via Homebrew or your preferred method, then run:`


mkcert -cert-file server.crt -key-file server.key localhost 127.0.0.1


2. start aem with tls support

info: Starting AEM dev server v14.26.1 info: Local AEM dev server up and running: https://localhost:3000/`

3. (optional) Add arguments to .env file:

`$ echo -e "AEM_TLS_CERT=server.crt\nAEM_TLS_KEY=server.key" >> .env`

`$3`

All the command arguments can also be specified via environment variables. the .envfile is loaded automatically.

example:

.env`dotenv AEM_OPEN=/products AEM_PORT=8080 AEM_PAGES_URL=https://stage.myproject.com`

#### HTTP Proxy

In order to use a HTTP proxy (eg behind a corporate firewall), you can set the respective environment variables:

Matching follows the following rules:

If present, ALL_PROXY is used as fallback if there is no other match.

#### Global

#### Up command

`Starting an import`

The AEM Importer is an application that supports importing content to AEM.

`$ cd $ aem import`

Read the full AEM Importer documentation.

`Developing AEM CLI`

`Testing`

You can use npm run checkto run the tests and check whether your code adheres to the aem-cli coding style.

`$3`

#### Development - Injectable scripts are inpackages/browser-injectables/src/- No build step required - scripts are used directly - Browser tests run only when injectable code changes

#### Testing Browser Injectables`bash cd packages/browser-injectables npm install npm test`

`Troubleshooting`

aem up `fails with` unable to get local issuer certificate

`$3`

The CA certificate is typically provided by your IT department. You can ask them for the CA certificate and save it to a file, e.g.my-ca.crt.

Then you can use the NODE_EXTRA_CA_CERTSenvironment variable to make Node.js trust the CA certificate:

`bash export NODE_EXTRA_CA_CERTS=my-ca.crt aem up`

`$3`

If you don't have access to the CA certificate from your IT department, you can extract it directly from your browser:

`bash export NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem aem up`

On Windows, use set instead of export:`cmd set NODE_EXTRA_CA_CERTS=./certs/hlx.page.pem aem up`

Either approach will make Node.js trust the server certificate and aem up should work.

npm install `fails with` File exists: /opt/homebrew/bin/hlx

If you try to install @adobe/aem-cli:

`> npm install -g @adobe/aem-cli ... npm error EEXIST: file already exists npm error File exists: /opt/homebrew/bin/hlx npm error Remove the existing file and try again, or run npm`

To solve, first uninstall the old version, then install again with the new name:

`npm uninstall -g @adobe/helix-cli npm install -g @adobe/aem-cli``

@adobe/aem-cli

AEM Command Line Interface (aem)

Status

Installation

Quick Start

Starting development

$3

$3

$3

@adobe/aem-cli

AEM Command Line Interface (aem)

Status

Installation

Quick Start

Starting development

$3

$3

$3

AEM Command Line Interface (`aem`)

`Quick Start`

`Starting development`

`$3`

`$3`

`$3`

AEM Command Line Interface (`aem`)

`Quick Start`

`Starting development`

`$3`

`$3`

`$3`