Node and npm

To use the AsyncAPI CLI tool, you must install NPM and Node.js version 16 or higher. To check if you already have both installed, run the following commands in your terminal:

1# check if node is installed
2node -v
3# or
4node --version
5
6# check if NPM is installed
7npm -v
8# or
9npm --version

If you don’t have Node.js or NPM installed, you can install both with this Node.js package manager.

After installing Node.js and NPM, run the following command to install the AsyncAPI ClI globally:

npm install -g @asyncapi/cli

To enable the autocomplete feature in the CLI for the shells bash and zshrc, there is a script that will run automatically and autocomplete is only support for bash and zshrc for the powershell refer to manually enabling autocomplete guide in ClI:

After the ClI installation :

if the configuration is not present logs will be:

✅ Autocomplete configuration added to .zshrc.

If the configuration is present for autocomplete logs:

✅ Autocomplete is already configured. Skipping addition.

To refresh the variables:

1 source ~/.bashrc   # For bash
2 source ~/.zshrc    # For zsh

Docker

Install Docker first, then you can either build the image locally or pull it from Docker Hub.

🏗️ Option 1: Build the image locally

Build the image using:

docker build   -t asyncapi/cli:latest   .

Run the image using:

1docker run --rm -it \
2  --user=root \
3  -v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
4  -v [GENERATED FILES LOCATION]:/app/output \
5  asyncapi/cli [COMMAND HERE]

Example

You can run this example inside the cli directory after cloning this repository.

1docker run --rm -it \
2  --user=root \
3  -v ${PWD}/test/integration/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \
4  -v ${PWD}/output:/app/output asyncapi/cli generate fromTemplate \
5  -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write

Note: Use backticks (`) instead of backslashes (\) when running on Windows.

🐳 Option 2: Pull the image from Docker Hub

Instead of building the image manually, you can pull the official image directly from Docker Hub:

docker pull asyncapi/cli

Then, run it the same way:

1docker run --rm -it \
2  --user=root \
3  -v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
4  -v [GENERATED FILES LOCATION]:/app/output \
5  asyncapi/cli [COMMAND HERE]
6

Example

1docker run --rm -it \
2  --user=root \
3  -v ${PWD}/test/integration/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \
4  -v ${PWD}/output:/app/output asyncapi/cli generate fromTemplate \
5  -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write

Mac

There are two ways to install the AsyncAPI CLI on your macOS: using the brew package manager or pkg files.

brew

To install the AsyncAPI CLI using the brew package manager, run the following commands in your terminal:

1# Install brew
2/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
3
4# Install AsyncAPI CLI
5brew install asyncapi

pkg

Every release of the AsyncAPI CLI has two macOS dedicated pkg file that enables you to install the CLI tool as a macOS application for x64 as well as arm64 architecture. To download the latest CLI release, run this command in your terminal:

1# For x64
2curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.x64.pkg
3
4# For arm64
5curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.arm64.pkg

To download a specific CLI release, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/download/<replace this with the specific CLI version e.g v0.13.0>/asyncapi.pkg

After downloading the AsyncAPI CLI, install it via the following command:

sudo installer -pkg asyncapi.pkg -target /

Windows

There are two ways to install the AsyncAPI CLI on your Windows operating system: using the chocolatey package manager or executable files.

Chocolatey

Prerequisites: Chocolatey must be installed on your Windows operating system. The installation instructions can be found here.

To install the AsyncAPI CLI using the chocolatey package manager, run the following command in your terminal with administrator privileges:

1# Install AsyncAPI CLI
2choco install asyncapi

To upgrade run this command:-

1# Upgrade AsyncAPI CLI
2choco upgrade asyncapi

To install a specific version run this command:

1# Install AsyncAPI CLI version xx.xx.xx
2choco install asyncapi --version xx.xx.xx

All the AsyncAPI CLI versions can be found here.

Executable files

Just install the appropriate installer and simply follow the default installation steps to complete the installation process.

Download asyncapi.x64.exe for 64-bit Windows and download asyncapi.x86.exe for 32-bit Windows.

Linux

Selecting the appropriate AsyncAPI CLI installation method on a Linux operating system depends on your Linux distro.

Debian based distros

For Debian based distros, you can install the AsycAPI CLI using the dpkg package manager for Debian.

curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.deb

To download a specific release of the CLI, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/download/<replace this with the specific CLI version e.g v0.13.0>/asyncapi.deb

Other distros

You can install the AsyncAPI CLI for other Linux distros using the archive tar.gz file.

For Alpine Linux / musl-based systems:

To download the latest Alpine-compatible release, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi-alpine.tar.gz

To download a specific Alpine-compatible release, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/download/<replace this with the specific CLI version e.g v0.13.0>/asyncapi-alpine.tar.gz

Once downloaded, untar the file:

tar -xzf asyncapi-alpine.tar.gz

For other Linux distributions (glibc-based):

To download the latest release of the CLI, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.tar.gz

To download a specific release of the CLI, run this command in your terminal:

curl -OL https://github.com/asyncapi/cli/releases/download/<replace this with the specific CLI version e.g v0.13.0>/asyncapi.tar.gz

Once you have downloaded the archived file, untar it by running this command in your terminal:

tar -xzf asyncapi.tar.gz

Setting up the symlink (for both Alpine and glibc versions):

The step above will create an AsyncAPI directory in the current path. To run the CLI from anywhere, you must create a symlink. If the current path you are on is /user/local/bin, for example, you must create the symlink in the /user/local/bin directory by following these steps:

1# cd into the unarchived directory
2cd asyncapi
3
4# get the absolute path
5pwd
6
7# Create a symlink
8ln -s <absolute-path>/bin/asyncapi /user/local/bin/asyncapi
9
10# The "asyncapi" command should be available to be used
11asyncapi

[!NOTE] If youare using Alpine Linux or any musl-based distribution, make sure to download the -alpine.tar.gz version to avoid glibc compatibility issues. The regular asyncapi.tar.gz file is compiled for glibc-based systems and will not work on Alpine.