@zonekit/cli

Command-line interface for Zonekit config validation, building, diffing, and publishing.

Use the zonekit CLI in your config repository or CI pipeline to validate authored config, build artifacts, compare versions, publish outputs, and promote a chosen version into a lock file.

Installation

pnpm add -D @zonekit/cli

Or install globally:

pnpm add -g @zonekit/cli

Before you start

The CLI assumes you already have:

• a zonekit.config.yaml file
• an optional contracts/ directory if you validate consumer contracts
• an optional adapter module if you publish to a CDN or storage provider

Typical workflow

zonekit validate --config zonekit.config.yaml --contracts ./contracts
zonekit build --config zonekit.config.yaml --out ./dist
zonekit diff --base ./dist/version.json --head ./dist/config.json --contracts ./contracts
zonekit publish --buildDir ./dist --out ./publish --adapter @acme/zonekit-upload-adapter
zonekit promote <version-hash> --lock ./zonekit.lock.json --artifactsDir ./publish

Recommended order:

1. validate before every change or in pre-merge CI.
2. build to produce the exact artifact set you will diff or publish.
3. diff to understand structural change and contract impact.
4. publish to stage or upload the chosen artifact set.
5. promote to move a known version into the lock file your app consumes.

Common commands

Validate

zonekit validate --config zonekit.config.yaml

Use --contracts ./contracts to enforce the surface promised to consuming apps, and --json for machine-readable CI output.

Build

zonekit build --config zonekit.config.yaml --outDir dist/

build validates first, then writes resolved artifacts into dist/ by default.

Diff

zonekit diff --base dist/version.json --head dist/config.json

Use --contracts ./contracts when you want per-app impact analysis. Use --json in automation.

Publish

zonekit publish --buildDir dist --out publish --adapter @acme/zonekit-upload-adapter

publish reads built artifacts from dist/ by default and writes published outputs to publish/. If you omit --adapter, it still prepares the publish output locally.

Promote

zonekit promote <version-hash> --lock zonekit.lock.json --artifactsDir publish

promote updates zonekit.lock.json by default and reads published artifacts from publish/.

Command summary

| Command | Purpose | Default paths | |---|---|---| | validate | Validate config and optional contracts | zonekit.config.yaml | | build | Validate and write resolved artifacts | config: zonekit.config.yaml, out: dist/ | | diff | Compare two config versions | base: dist/version.json, head: dist/config.json | | publish | Publish or stage built artifacts | buildDir: dist/, out: publish/ | | promote | Update the lock file to a chosen version | lock: zonekit.lock.json, artifactsDir: publish/ |

Run zonekit <command> --help for command-specific options.

Programmatic usage

import { runCli } from "@zonekit/cli";

const exitCode = await runCli(["validate", "--config", "./zonekit.config.yaml"], {
  stdout: console.log,
  stderr: console.error,
});

API overview

• runCli(argv, runtime) -- Run the CLI with given arguments and stdout/stderr handlers, returns exit code

License

MIT

Read more:

• Config plane overview
• @zonekit/cli package docs
• Quickstart