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 & internals4│ └── api/ # REST API (Express)5├── domains/6│ ├── models/ # Specification, Context7│ └── services/ # Business logic8├── errors/ # Custom errors9├── interfaces/ # TypeScript types10└── utils/ # Utilities
Core 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 → ServiceResult
API Request:
HTTP Request → Express → Controller → Domain Service → HTTP Response
Extension 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 |
Create Issue on GitHub