ZeroCore CLI

@zero.core/cli is the general command-line tool for the ZeroCore ecosystem. It is not limited to @zero.core/api-framework, but the first implemented command group focuses on API project creation, API code generation, OpenAPI utilities, DI inspection, scheduled task operations, pub/sub inspection, and client generation.

Install

During local development, run it from this package directory:

cd packages/zerocore-cli
yarn install --ignore-scripts
yarn dev -- --help

The CLI package does not depend on @zero.core/api-framework at install time. API projects generated by the CLI declare their own framework dependency.

Install the published package from npm:

npm install -D @zero.core/cli
npx zerocore --help

The CLI performs a best-effort version check against the npm registry and writes update notices to stderr. It never fails a command when the registry is unavailable. Disable the check with --no-version-check or ZEROCORE_CLI_VERSION_CHECK=0.

Commands

Project Scaffolding

Create a new API project:

zerocore new api orders-api --dir apps

This creates a TypeScript Express API using @zero.core/api-framework, controller discovery, ServiceContainer, global error handling, and a health endpoint.

Create a generic app or package:

zerocore new app worker-service --dir apps
zerocore new package contracts --dir packages

Use --force to overwrite existing generated files.

API Generation

Generate a complete CRUD-style resource:

zerocore api generate resource Project --dir src

This creates:

• src/models/ProjectModels.ts
• src/services/ProjectService.ts
• src/controllers/ProjectsController.ts
• test/ProjectsController.test.ts

Generate individual pieces:

zerocore api generate controller Project --dir src
zerocore api generate service Project --dir src
zerocore api generate dto ProjectDto --dir src
zerocore api generate test Projects --dir src
zerocore api generate subscriber ProjectEvents --topic projects.created --provider redis-streams --dir src

Generated controllers use C#-style ZeroCore decorators such as @ApiController, @Route, @HttpGet, @FromRoute, @FromBody, @ProducesResponseType, and explicit @Inject constructor metadata.

Generated subscribers use @Subscribe, @MessageBody, @MessageEnvelope, and provider-agnostic framework imports from @zero.core/api-framework.

Doctor

Inspect an API project for common framework convention issues:

zerocore doctor api --dir apps/api
zerocore doctor api --dir apps/api --json

Current checks include controller metadata, route metadata, response metadata, model metadata, and basic project structure.

OpenAPI Utilities

Validate an OpenAPI document:

zerocore api openapi validate openapi.json

Print an OpenAPI document:

zerocore api openapi print openapi.json
zerocore api openapi print openapi.json --min

Diff two OpenAPI documents:

zerocore api openapi diff openapi-v1.json openapi-v2.json
zerocore api openapi diff openapi-v1.json openapi-v2.json --json

The diff command exits with code 1 when removed operations or schemas are detected.

Client Generation

Generate a lightweight fetch client from an OpenAPI document:

zerocore api client generate \
  --input openapi.json \
  --output src/generated/client.ts \
  --name ZeroCoreClient

Use --options-name to customize the generated client options interface name.

DI Inspection

Print a static dependency graph:

zerocore api di graph --dir src
zerocore api di graph --dir src --json

Validate explicit DI metadata:

zerocore api di validate --dir src

The validator reports constructor parameters without explicit metadata and simple circular dependencies discovered from @Inject, @Injectable(...tokens), and static inject/dependencies arrays.

Scheduled Tasks

List tasks discovered from a task directory:

zerocore api tasks list --dir src/tasks
zerocore api tasks list --dir src/tasks --json

Directory discovery loads @zero.core/api-framework from the target API project, so that project must have the framework installed.

Run one task by name:

zerocore api tasks run cleanup --dir src/tasks

For projects with custom DI setup, export a scheduler from a module:

zerocore api tasks list --module src/tasks/scheduler.ts
zerocore api tasks run cleanup --module src/tasks/scheduler.ts

The module may export scheduler, default, createScheduler, or createTaskScheduler.

Pub/Sub

List the implemented provider packages and their provider registration classes:

zerocore api pubsub providers
zerocore api pubsub providers --json

Scan decorated subscribers:

zerocore api pubsub scan --dir src
zerocore api pubsub scan --dir src --json

Validate subscriber metadata:

zerocore api pubsub validate --dir src

The scanner is static and checks @Subscribe(...) usage without requiring the target API project to execute.

Current Scope

Implemented:

• project scaffolding
• API resource/controller/service/DTO/test generation
• API doctor checks
• OpenAPI validate/print/diff
• TypeScript client generation from OpenAPI
• DI graph and validation
• scheduled task list/run helpers
• pub/sub provider catalog, subscriber scanning, subscriber validation, and subscriber generation
• best-effort update notices for newer published CLI versions

Not implemented in this package yet:

• documentation site helpers
• agent setup/publishing helpers

Verification

cd packages/zerocore-cli
yarn typecheck
yarn test
yarn build

For the full staged gate:

yarn test:production

Stage meaning:

• typecheck verifies CLI source, command contracts, and generated TypeScript helper code.
• test runs command-level tests for entrypoint behavior, scaffolding, generation, doctor checks, OpenAPI utilities, client generation, DI inspection, task commands, package contracts, and failure paths.
• build verifies the publishable dist binary and declarations are emitted.

Production Notes

• The runtime binary is zerocore.
• The CLI package itself does not depend on @zero.core/api-framework; generated API projects declare their own framework dependency.
• Commands should return non-zero exit codes with concise stderr diagnostics when validation fails.
• Version update notices are written to stderr, are skipped in CI by default, and can be disabled with --no-version-check or ZEROCORE_CLI_VERSION_CHECK=0.
• The npm package payload is compiled dist output plus README.md, LICENSE, and NOTICE.
• Do not document or add docs-helper, agent setup, publishing, or marketplace commands unless they are explicitly implemented.