HazelJS CLI Package

@hazeljs/​cli scaffolds HazelJS applications, generates components, and manages packages. For Agent OS, clone Meridian first — the CLI is not a substitute for the flagship DNA / Store / Skillgate / HITL / apply path.

Quick Reference

• Purpose: Scaffold HazelJS projects and generate controllers/services/agents; Agent OS DNA smoke via hazel agent … where available.
• When to use: Framework app scaffolding, generators, and package add — after (or instead of) Meridian when you only need a thin app.
• Primary Agent OS path: Meridian store:sync → platform:sync → dev — not hazel new --template ai-native.
• Key concepts: hazel new, hazel generate, hazel add, hazel agent (run/apply/store), hazel eval.
• Dependencies: Install globally with npm install -g @hazeljs/​cli.
• Common mistakes: Treating ai-native template as the Agent OS flagship; using hazel agent run (DNA stubs) as a substitute for real /​api/​chat execute.

Agent OS first

# Flagship teaching path (recommended)
git clone https://github.com/​hazel-js/​hazeljs-meridian-ops.git
cd hazeljs-meridian-ops && npm i && npm run store:sync && npm run platform:sync && npm run dev

Anti-confusion: hazel agent run = DNA smoke with stubs. Real tools and HITL = your app’s runtime.execute / Meridian /​api/​chat. hazel agent apply declares desired state — it does not restart Node.

Installation

Install globally to use the hazel command anywhere:

npm install -g @hazeljs/​cli

Or use it via npx without installing:

npx @hazeljs/​cli new my-app

Architecture

The CLI uses a template-based generation system powered by Mustache. Every generator follows the same pattern: accept a name, resolve template data, render the template, and write the file.

graph LR
  A["hazel g controller users"] --> B["Generator Base Class"]
  B --> C["Mustache Template Engine"]
  C --> D["users.controller.ts"]

  style A fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
  style B fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
  style C fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
  style D fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff

Key design decisions:

• Config-driven simple generators — 17+ single-file generators (controller, service, guard, agent, etc.) are defined as configuration objects in a single file, eliminating code duplication
• Centralized package registry — all HazelJS package metadata (npm names, import hints, module imports, setup templates) lives in one place, used by both hazel add and hazel new -i
• Unified Generator class — every generator extends a base class with a suffix property, so files are consistently named (name.controller.ts, name.service.ts, name.guard.ts, etc.)
• Shared utilities — toPascalCase, toKebabCase, toCamelCase, and renderTemplate live in one place and are used by all generators
• --dry-run support — every generator can preview what it would create without writing anything

Creating a New Application

Quick skeleton (fastest)

hazel g app my-app
cd my-app
npm install
npm run dev

This generates a minimal HazelJS application skeleton from the CLI template (without running installs or git init).

Full scaffolding (recommended for interactive setup)

hazel new my-app

This scaffolds a complete HazelJS project with:

• src/​index.ts — entry point with CORS and proper HazelApp bootstrap
• src/​app.module.ts — root module with @HazelModule decorator
• src/​hello.controller.ts — example controller
• package.json — dependencies, scripts (build, start, dev, test, lint, format), ESLint devDependencies
• tsconfig.json — TypeScript config with decorators, strict mode, and rootDir: .​/src
• .eslintrc.js — ESLint config with TypeScript and Prettier
• .gitignore — sensible defaults

Interactive Mode

hazel new my-app --interactive
# or
hazel new my-app -i

Interactive mode walks you through project setup:

1. Description — project description for package.json
2. Author — your name
3. License — Apache-2.0 (default), MIT, GPL-3.0, BSD-3-Clause, or ISC
4. Packages — select additional HazelJS packages to install

When you select packages in interactive mode, the CLI automatically:

• Installs the npm packages
• Updates app.module.ts with the correct imports and module registration
• Creates .env and .env.example files when Config is selected
• Sets up Swagger integration in index.ts when Swagger is selected

Available packages in interactive mode

Options

hazel eval (golden dataset smoke check)

Loads a golden dataset JSON file through @hazeljs/​eval using a placeholder runner (pass-through) to verify shape and dependencies. Use --ci to exit with code 1 when thresholds fail—useful in pipelines before you wire a real RAG or agent runner.

For production evaluation, call runGoldenDataset from your own script with HazelAI, agents, or RAG services. See the Eval package.

hazel eval .​/eval/​golden.json
hazel eval .​/eval/​golden.json --ci

Generating Components

All generators live under hazel generate (alias: hazel g). Every generator supports:

• -p, --path <path> — custom output directory
• --dry-run — preview files without writing them
• --json — output a single JSON object with created paths and next steps

To discover everything that can be generated:

hazel g --list

For JSON output:

hazel g --list --list-json

Quick Reference

Core Generators

Controller

hazel g controller users
# alias: hazel g c users

Generates users.controller.ts:

import { Controller, Get, Post, Body, Param, Delete, Put } from '@hazeljs/​core';
import { UsersService } from '.​/users.service';
import { CreateUsersDto } from '.​/dto/​create-users.dto';
import { UpdateUsersDto } from '.​/dto/​update-users.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.usersService.findOne(id);
  }

  @Post()
  create(@Body(CreateUsersDto) createDto: CreateUsersDto) {
    return this.usersService.create(createDto);
  }

  @Put(':id')
  update(@Param('id') id: string, @Body(UpdateUsersDto) updateDto: UpdateUsersDto) {
    return this.usersService.update(id, updateDto);
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return this.usersService.remove(id);
  }
}

Service

hazel g service users
# alias: hazel g s users

Generates users.service.ts:

import { Service } from '@hazeljs/​core';

@Service()
export class UsersService {
  constructor() {}

  async findAll() {
    return [];
  }

  async findOne(id: string) {
    return { id };
  }

  async create(createDto: any) {
    return createDto;
  }

  async update(id: string, updateDto: any) {
    return { id, ...updateDto };
  }

  async remove(id: string) {
    return { id };
  }
}

Module

hazel g module users
# alias: hazel g m users

Generates a complete feature module with 5 files in src/​users/​:

/​/​ users.module.ts
import { HazelModule } from '@hazeljs/​core';
import { UsersController } from '.​/users.controller';
import { UsersService } from '.​/users.service';

@HazelModule({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

DTO (Data Transfer Objects)

hazel g dto product
# alias: hazel g d product

Generates two files in src/​dto/​:

/​/​ product.dto.ts (Create)
import { IsString, IsOptional } from 'class-validator';

export class CreateProductDto {
  @IsString()
  name: string;

  @IsString()
  @IsOptional()
  description?: string;
}

/​/​ update-product.dto.ts (Update)
import { IsString, IsOptional } from 'class-validator';

export class UpdateProductDto {
  @IsString()
  @IsOptional()
  name?: string;

  @IsString()
  @IsOptional()
  description?: string;
}

Guard

hazel g guard auth
# alias: hazel g gu auth

Generates auth.guard.ts:

import { Service, type CanActivate, type ExecutionContext } from '@hazeljs/​core';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    /​/​ Add your guard logic here
    return true;
  }
}

Interceptor

hazel g interceptor logging
# alias: hazel g i logging

Generates logging.interceptor.ts:

import { Service, Interceptor, type ExecutionContext } from '@hazeljs/​core';

@Injectable()
export class LoggingInterceptor implements Interceptor {
  async intercept(context: ExecutionContext, next: () => Promise<unknown>): Promise<unknown> {
    /​/​ Pre-processing logic here
    const result = await next();
    /​/​ Post-processing logic here
    return result;
  }
}

Middleware

hazel g middleware logger
# alias: hazel g mw logger

Generates logger.middleware.ts:

import { Service, type MiddlewareHandler, type Request, type Response, type NextFunction } from '@hazeljs/​core';

@Injectable()
export class LoggerMiddleware implements MiddlewareHandler {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`[LoggerMiddleware] ${req.method} ${req.url}`);
    next();
  }
}

Exception Filter

hazel g filter http
# alias: hazel g f http

Generates http.filter.ts:

import { Catch, type ExceptionFilter, type ArgumentsHost, HttpError, logger } from '@hazeljs/​core';

@Catch(HttpError)
export class HttpExceptionFilter implements ExceptionFilter<HttpError> {
  catch(exception: HttpError, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();

    const status = exception.statusCode || 500;
    const message = exception.message || 'Internal server error';

    logger.error(`[${request.method}] ${request.url} - ${message} (${status})`);

    response.status(status).json({
      statusCode: status,
      message,
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }
}

Pipe

hazel g pipe validation

Generates validation.pipe.ts:

import { type PipeTransform, type RequestContext } from '@hazeljs/​core';

export class ValidationPipe implements PipeTransform {
  transform(value: unknown, context: RequestContext): unknown {
    /​/​ Transform logic here
    return value;
  }
}

CRUD Generator

The CRUD generator creates a complete REST resource in one command:

hazel g crud product

This generates 4 files in src/​product/​:

Custom Route Path

hazel g crud product -r api/​v1/​products

This sets the controller route to /​api/​v1/​products instead of the default /​product.

Auth Generator

Scaffolds a complete authentication module in one command:

hazel g auth

Generates 6 files in src/​auth/​:

After generating, follow the next steps printed by the CLI:

1. Import AuthModule in your app module
2. Configure JwtModule.forRoot({ secret: "your-secret", expiresIn: "1d" })
3. Install bcryptjs: npm install bcryptjs @types/​bcryptjs
4. Implement database integration in AuthService

Package-Specific Generators

WebSocket Gateway

hazel g gateway chat
# alias: hazel g ws chat

Generates chat.gateway.ts using @hazeljs/​websocket:

import { Realtime, OnConnect, OnDisconnect, OnMessage, Subscribe, Client, Data, WebSocketClient } from '@hazeljs/​websocket';

@Realtime('/​chat')
export class ChatGateway {
  @OnConnect()
  handleConnection(@Client() client: WebSocketClient) {
    console.log('Client connected:', client.id);
  }

  @OnDisconnect()
  handleDisconnect(@Client() client: WebSocketClient) {
    console.log('Client disconnected:', client.id);
  }

  @Subscribe('message')
  @OnMessage('message')
  handleMessage(@Client() client: WebSocketClient, @Data() data: unknown) {
    console.log('Message received from', client.id, ':', data);
  }
}

Repository (Prisma)

hazel g repository user
# alias: hazel g repo user

Generates user.repository.ts extending BaseRepository from @hazeljs/​prisma:

import { Repository } from '@hazeljs/​prisma';
import { PrismaService } from '@hazeljs/​prisma';

@Repository({ model: 'user' })
export class UserRepository extends BaseRepository<any> {
  constructor(prisma: PrismaService) {
    super(prisma.client.modelName);
  }

  async findByName(name: string) {
    return this.findMany({ where: { name } });
  }
}

AI Service

hazel g ai-service chat
# alias: hazel g ai chat

Generates chat.ai-service.ts using @hazeljs/​ai:

import { Service } from '@hazeljs/​core';
import { AIEnhancedService, AIFunction, AIPrompt } from '@hazeljs/​ai';

@Service()
export class ChatAIService {
  constructor(private readonly aiService: AIEnhancedService) {}

  @AIFunction({
    provider: 'openai',
    model: 'gpt-4',
    streaming: false,
  })
  async chatTask(@AIPrompt() prompt: string): Promise<unknown> {
    const result = await this.aiService.complete({
      provider: 'openai',
      model: 'gpt-4',
      messages: [{ role: 'user', content: prompt }],
    });
    return result;
  }
}

AI Agent

hazel g agent research

Generates research.agent.ts using @hazeljs/​agent:

import { Agent, Tool } from '@hazeljs/​agent';

@Agent({
  name: 'research',
  description: 'A research agent',
  systemPrompt: 'You are a helpful Research agent.',
  enableMemory: true,
  enableRAG: true,
})
export class ResearchAgent {
  @Tool({
    description: 'Example tool for research',
    parameters: [
      { name: 'input', type: 'string', description: 'Input parameter', required: true },
    ],
  })
  async exampleTool(input: { input: string }): Promise<{ result: string }> {
    return { result: `Processed: ${input.input}` };
  }
}

Serverless Handler

# AWS Lambda (default)
hazel g serverless api
# alias: hazel g sls api

# Google Cloud Function
hazel g serverless api --platform cloud-function

Generates api.handler.ts:

/​/​ Lambda
import { createLambdaHandler } from '@hazeljs/​serverless';
import { AppModule } from '.​/app.module';
export const handler = createLambdaHandler(AppModule);

/​/​ Cloud Function
import { createCloudFunctionHandler } from '@hazeljs/​serverless';
import { AppModule } from '.​/app.module';
export const handler = createCloudFunctionHandler(AppModule);

Config

hazel g config

Generates app.config.ts with setup instructions for @hazeljs/​config:

import { ConfigModule, ConfigService } from '@hazeljs/​config';

/​/​ Add to your app module imports:
/​/​ ConfigModule.forRoot({ envFilePath: '.env' })
/​/​
/​/​ Inject and use:
/​/​ this.config.get('DATABASE_URL');
/​/​ this.config.get('PORT', '3000');  /​/​ with default

Cache

hazel g cache product

Generates product.cache.ts with @Cacheable and @CacheEvict decorators from @hazeljs/​cache:

import { Service } from '@hazeljs/​core';
import { CacheService, Cacheable, CacheEvict } from '@hazeljs/​cache';

@Service()
export class ProductCacheService {
  constructor(private readonly cacheService: CacheService) {}

  @Cacheable({ key: 'product:all', ttl: 60 })
  async findAll() {
    return [];
  }

  @CacheEvict({ key: 'product:all' })
  async create(data: any) {
    return data;
  }
}

Cron Jobs

hazel g cron cleanup
# alias: hazel g job cleanup

Generates cleanup.cron.ts with @Cron decorator from @hazeljs/​cron:

import { Service } from '@hazeljs/​core';
import { Cron, CronExpression } from '@hazeljs/​cron';

@Service()
export class CleanupCronService {
  @Cron(CronExpression.EVERY_MINUTE)
  handleEveryMinute() {
    console.log('[CleanupCron] Running every minute...');
  }

  @Cron('0 0 * * *') /​/​ Every day at midnight
  handleDaily() {
    console.log('[CleanupCron] Running daily task...');
  }

  @Cron(CronExpression.EVERY_HOUR)
  handleHourly() {
    console.log('[CleanupCron] Running hourly cleanup...');
  }
}

RAG (Retrieval-Augmented Generation)

hazel g rag knowledge

Generates knowledge.rag.ts using @hazeljs/​rag:

import { Service } from '@hazeljs/​core';
import { RAGPipeline, MemoryVectorStore } from '@hazeljs/​rag';

@Service()
export class KnowledgeRagService {
  private pipeline: RAGPipeline;

  constructor() {
    const vectorStore = new MemoryVectorStore();
    this.pipeline = new RAGPipeline({ vectorStore, topK: 5 });
  }

  async addDocument(content: string, metadata?: Record<string, unknown>) {
    await this.pipeline.addDocument({ content, metadata: metadata || {} });
  }

  async query(question: string) {
    return this.pipeline.query(question);
  }
}

Service Discovery

hazel g discovery app

Generates app.discovery.ts using @hazeljs/​discovery:

import { Service } from '@hazeljs/​core';
import { ServiceRegistry, DiscoveryClient } from '@hazeljs/​discovery';

@Service()
export class AppDiscoveryService {
  constructor(
    private readonly registry: ServiceRegistry,
    private readonly client: DiscoveryClient,
  ) {}

  async registerService() {
    await this.registry.register({
      name: 'app-service',
      host: 'localhost',
      port: 3000,
      metadata: { version: '1.0.0' },
    });
  }

  async discoverService(serviceName: string) {
    return this.client.getInstances(serviceName);
  }
}

Adding Packages

The hazel add command installs HazelJS packages and shows usage hints:

hazel add auth

This runs npm install @hazeljs/​auth and prints:

Usage:
  import { JwtModule } from "@hazeljs/​auth";
  /​/​ JwtModule.forRoot({ secret: "your-secret", expiresIn: "1d" })

Generate a setup file

Use --setup to also generate a minimal starter file for the package:

hazel add swagger --setup
# Installs @hazeljs/​swagger AND creates swagger.setup.ts

hazel add oauth --setup
hazel add kafka --setup

This replaces the old hazel g setup <package> command. The generated *.setup.ts file contains a ready-to-edit snippet so you can wire the package in without hunting through docs.

Interactive mode

hazel add

Without a package name, it shows an interactive list of all available packages.

Available packages

Utility Commands

Info

Display information about the current HazelJS project:

hazel info

The --dry-run Flag

Every generator supports --dry-run to preview what would be created without writing any files:

hazel g module users --dry-run

Without --json, the CLI prints human-readable lines such as [dry-run] Would create /​path/​to/​src/​users/​users.module.ts for each file.

The --json Flag

If you want machine-readable output, add --json. The CLI prints a single JSON object to stdout with ok, created (file paths), and optional nextSteps.

hazel g controller users --json

Example output (with --json):

{"ok":true,"created":["/​path/​to/​project/​src/​users.controller.ts"]}

With --dry-run --json you get the same shape; created lists the paths that would be written. This is useful for scripts and automation.

Real-World Workflows

Building a REST API

Option A — Quick skeleton (no install/git):

hazel g app my-api
cd my-api
npm install
# Then generate features as below

Option B — Full interactive setup:

# 1. Create the project
hazel new my-api -i
# Select: config, swagger, prisma, auth

# 2. Generate the users feature
hazel g crud users

# 3. Generate the products feature
hazel g module products
hazel g repository product

# 4. Add caching
hazel add cache
hazel g cache product

# 5. Add cron jobs for cleanup
hazel add cron
hazel g cron cleanup

Building an AI Application

Option A — Quick skeleton: hazel g app ai-app then cd ai-app && npm install.

Option B — Interactive:

# 1. Create the project
hazel new ai-app -i
# Select: config, ai

# 2. Generate an AI service
hazel g ai-service chat

# 3. Add RAG for document retrieval
hazel add rag
hazel g rag knowledge

# 4. Create an AI agent
hazel add agent
hazel g agent research

Building a Real-Time Application

# 1. Create the project
hazel new realtime-app -i
# Select: config, auth, websocket

# 2. Generate auth module
hazel g auth

# 3. Generate WebSocket gateways
hazel g gateway chat
hazel g gateway notifications

Going Serverless

# 1. Create the project
hazel new serverless-api

# 2. Add serverless support
hazel add serverless

# 3. Generate the handler
hazel g serverless api --platform lambda
# or for GCP:
hazel g serverless api --platform cloud-function

Best Practices

1. Use modules to organize features — Run hazel g module <feature> to get the full structure, then customize from there.

2. Always use --dry-run first — Preview what will be generated before committing to disk.

3. Leverage aliases — Use hazel g c, hazel g s, hazel g m for speed.

4. Use -p for organization — Place controllers in feature directories: hazel g c users -p src/​users.

5. Start with CRUD — For standard REST resources, hazel g crud <name> gives you everything in one shot.

6. Use interactive mode for new projects — hazel new my-app -i sets up everything correctly from the start. For a minimal skeleton without installs, use hazel g app my-app then cd my-app && npm install.

What's Next?

• Learn about Controllers for building REST APIs
• Explore Modules for organizing your application
• Set up Authentication with JWT
• Add Caching for performance
• Build AI features with the AI package and Agent package
• Regression-test AI behavior with the Eval package (hazel eval or runGoldenDataset in code)

Related Resources

• Eval Package – Golden datasets and runGoldenDataset for real evals
• Core Package – HazelJS framework fundamentals
• Config Package – Configuration management
• Auth Package – Authentication scaffolding
• Cache Package – Performance optimization
• All Packages – Complete package list

Recipes

Recipe: Scaffold a New Project

# Prefer Agent OS flagship first:
# git clone https://github.com/​hazel-js/​hazeljs-meridian-ops.git

# Minimal skeleton (framework only)
npx @hazeljs/​cli g app my-app

# AI-Native application with agents, RAG, PostgreSQL, Docker
# (secondary — not the Meridian /​ Agent OS teaching path)
npx @hazeljs/​cli g app my-ai-app --template=ai-native

# Full interactive setup with package selection
npx @hazeljs/​cli new my-app -i

Recipe: Generate Components

# Generate a complete CRUD resource (recommended)
hazel g crud users

# Generate individual components
hazel g controller users
hazel g service users
hazel g module users

# Generate an AI agent
hazel g agent support

Recipe: Golden dataset smoke check

Validates a golden JSON file with @hazeljs/​eval and a placeholder runner. Use --ci for a non-zero exit when scores fail. For real RAG or agent checks, use runGoldenDataset in application code — see Eval package.

hazel eval .​/eval/​golden.json
hazel eval .​/eval/​golden.json --ci