CLI Architecture

Overview

The AsyncAPI CLI is built with oclif and provides both command-line operations and a REST API server for working with AsyncAPI specifications.

Architecture Diagram

1┌─────────────────────────────────────────────────┐
2│  Entry Points                                   │
3│  ┌──────────┐              ┌──────────┐         │
4│  │   CLI    │              │   API    │         │
5│  │  (oclif) │              │ (Express)│         │
6│  └────┬─────┘              └────┬─────┘         │
7└───────┼─────────────────────────┼───────────────┘
8        └───────────┬─────────────┘
9                    ▼
10        ┌───────────────────────┐
11        │   Domain Services     │
12        │  Validation, Generator│
13        │  Convert, Config      │
14        └───────────┬───────────┘
15                    ▼
16        ┌───────────────────────┐
17        │   Domain Models       │
18        │  Specification,Context│
19        └───────────┬───────────┘
20                    ▼
21        ┌───────────────────────┐
22        │   Utilities           │
23        │  Logger, Helpers      │
24        └───────────────────────┘

Directory Structure

1src/
2├── apps/
3│   ├── cli/              # CLI commands & internals
4│   └── api/              # REST API (Express)
5├── domains/
6│   ├── models/           # Specification, Context
7│   └── services/         # Business logic
8├── errors/               # Custom errors
9├── interfaces/           # TypeScript types
10└── utils/                # Utilities

Core Components

CLI Application

Commands:

• Core: validate, convert, format, optimize, diff, bundle
• Generation: generate client, generate models, generate fromTemplate
• Config: config context, config analytics, config versions
• Utility: new file, new template, start api|studio|preview, pretty (Studio for start studio/preview is installed on-demand, not bundled)

API Server

Endpoints: /v1/validate, /v1/parse, /v1/generate, /v1/convert, /v1/bundle, /v1/diff, /v1/docs, /v1/help, /v1/version

Features: Express with Helmet security, CORS, compression, RFC 7807 error responses

Domain Services

All services extend BaseService and return ServiceResult<T>:

Domain Models

Error Classes

ContextError, SpecificationFileError, ValidationError, GeneratorError, DiffError

Execution Flow

CLI Command:

User Command → oclif → Base Command → Domain Service → ServiceResult

API Request:

HTTP Request → Express → Controller → Domain Service → HTTP Response

Extension Points

Configuration

Environment Variables:

• NODE_ENV — development | production | test
• PORT — API server port (default: 3000)
• ASYNCAPI_METRICS_* — Metrics configuration

Technology Stack

Workspace packages (monorepo)

This repository is an npm-workspaces + Turborepo monorepo. The root package is @asyncapi/cli (still published from the repo root). workspaces includes both "." and packages/* so Changesets versions the CLI the same way it does today (npx changeset → select @asyncapi/cli) and also versions workspace packages such as @asyncapi/optimizer. Additional publishable packages live under packages/*:

Turbo orders builds so @asyncapi/optimizer is built before the root CLI (whose build compiles the optimize command that imports it). Use npm run optimizer:build / npm run optimizer:test to work on it in isolation. See the package spec on GitHub: docs/optimizer/spec.md.