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/ # UtilitiesCore Components
CLI Application
| Component | Description |
|---|---|
| Entry Points | bin/run (dev), bin/run_bin (prod) |
| Base Command | Metrics, parser integration, error handling |
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
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>:
| Service | Purpose |
|---|---|
ValidationService | Validates specs with Spectral, calculates scores |
GeneratorService | Generates code/models |
ConvertService | Converts between AsyncAPI/OpenAPI formats |
ConfigService | Manages CLI config and contexts |
ArchiverService | Creates ZIP archives |
Domain Models
| Model | Purpose |
|---|---|
| Specification | Loads from file, URL, or context; auto-detects asyncapi.json|yml|yaml |
| Context | Manages multiple AsyncAPI contexts; stored in ~/.asyncapi/ |
Error Classes
ContextError, SpecificationFileError, ValidationError, GeneratorError, DiffError
Execution Flow
CLI Command:
User Command → oclif → Base Command → Domain Service → ServiceResultAPI Request:
HTTP Request → Express → Controller → Domain Service → HTTP ResponseExtension Points
| Add | Steps |
|---|---|
| New Command | Create in src/apps/cli/commands/, extend Command, implement run() |
| New API Endpoint | Create controller in src/apps/api/controllers/, register in index.ts |
| New Service | Create in src/domains/services/, extend BaseService, return ServiceResult<T> |
Configuration
| Config | Location |
|---|---|
| CLI Context | ~/.asyncapi/contexts.json, ~/.asyncapi/.current |
| Analytics | ~/.asyncapi-analytics |
Environment Variables:
NODE_ENV—development|production|testPORT— API server port (default: 3000)ASYNCAPI_METRICS_*— Metrics configuration
Technology Stack
| Category | Technologies |
|---|---|
| Core | oclif, TypeScript, Express |
| AsyncAPI | @asyncapi/parser, generator, converter, bundler, diff, optimizer |
| Supporting | winston, ajv, chalk, @clack/prompts |
