CLI and production readiness — dhal Documentation

dhal documentation

Page 8 of 9

The dhal CLI is included with @rokadhq/dhal and can be run through npx dhal.

Core commands

bash

npx dhal add
npx dhal init
npx dhal test-config
npx dhal migrate --check
npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal openapi inspect openapi.json
npx dhal openapi generate openapi.yaml
npx dhal readiness --production
npx dhal compat
npx dhal stability
npx dhal rules
npx dhal presets list
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json
npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

Guided project onboarding

bash

npx dhal add

dhal add detects:

Express, Fastify, NestJS, Koa, or Hono from package.json;
npm, pnpm, Yarn, or Bun from the project lockfile;
whether @rokadhq/dhal is already installed.

The default invocation is read-only. It previews a framework preset, a monitor-mode dhal.json, a separate integration module, the correct install command, and registration instructions.

Write the proposed files after review:

bash

npx dhal add --write

Useful options:

text

--framework <name>       Override detection with express, fastify, nestjs, koa, hono, or node-http
--config <path>          Configuration output path
--integration <path>     Generated integration-module path
--write                  Create proposed files
--force                  Overwrite existing generated output

The command never patches existing application source automatically.

Initialize, validate, and migrate

bash

npx dhal init
npx dhal test-config
npx dhal migrate --check

init creates a generic monitor-first configuration. test-config parses and validates the effective configuration. migrate --check reports whether migration is required without changing files.

Use migrate --write only after reviewing the proposed migration and committing the current file.

Doctor and conservative repair

bash

npx dhal doctor
npx dhal doctor --fix --dry-run
npx dhal doctor --fix

Doctor identifies configuration and environment findings that can weaken production behaviour.

doctor --fix deliberately has a narrow scope. It may:

create a missing monitor-mode starter configuration;
migrate a supported pre-schemaVersion configuration;
create dhal.json.bak before changing an existing file.

It does not enable blocking, trust proxy headers, Redis, reputation providers, OpenTelemetry, or webhooks automatically. Use --dry-run to preview repairs and --no-backup only when another backup mechanism is already in place.

Framework presets

bash

npx dhal presets list
npx dhal presets show nestjs-api
npx dhal presets apply hono-node-api --output dhal.hono.json

Version 1.1 adds monitor-first framework presets:

text

express-api
fastify-api
nestjs-api
koa-api
hono-node-api
node-http-api

The existing operational presets remain available, including starter, api-production, auth-hardened, strict-json-api, behind-proxy, and observability.

Presets are explicit configuration overlays. Review and validate generated output before deployment.

OpenAPI inspection

Inspect an OpenAPI description without generating configuration:

bash

npx dhal openapi inspect openapi.json
npx dhal openapi inspect openapi.yaml

JSON documents are parsed structurally. YAML uses a conservative scanner for common OpenAPI path, method, tag, security, and request-content declarations. Complex YAML using anchors, merge keys, or external references should be converted to JSON first.

Inspection classifies signals such as:

authentication operations;
uploads and multipart requests;
webhooks and callbacks;
expensive search, export, batch, report, or inference operations;
explicitly public operations;
JSON request bodies.

Generate monitor-mode policy from OpenAPI

Preview generated policy:

bash

npx dhal openapi generate openapi.yaml

OpenAPI parameters are converted to Dhal wildcard paths:

text

/users/{userId}              -> /users/*
/orgs/{orgId}/users/{userId} -> /orgs/*/users/*

Every generated route remains in monitor mode. Existing owner-managed route profiles are preserved and reported as preserve-existing.

Write into dhal.json with a backup:

bash

npx dhal openapi generate openapi.yaml --config dhal.json --write

Or write a separate proposal:

bash

npx dhal openapi generate openapi.json --output dhal.openapi.json

Use --force to replace an existing separate output, --no-backup to suppress the configuration backup, and --default-max to change the default generated rate limit.

Generated policy is a security proposal, not an authorization model. Review grouped HTTP methods, route classifications, rate limits, and content-type assumptions before enforcement.

Readiness, compatibility, and stability

bash

npx dhal readiness --production
npx dhal compat
npx dhal stability

Readiness evaluates whether configuration is suitable for production enforcement. Compatibility reports the tested runtime and integration matrix. Stability reports the contract level of public API surfaces.

Treat readiness as one deployment input, not a replacement for replay testing or application-specific review.

Rules, replay, and simulation

bash

npx dhal rules
npx dhal replay fixtures.replay.json
npx dhal simulate fixtures.simulation.json

Keep replay fixtures for known-good and known-malicious requests in version control. A production promotion should fail when known-good traffic unexpectedly blocks or malicious fixtures stop matching the expected control.

CI policy

The policy.ci section can enforce organization requirements:

json

{
  "policy": {
    "ci": {
      "failOnModes": ["off"],
      "requireWebhookSigning": true,
      "requireNonMonitorRouteForRules": ["credential_stuffing.threshold_exceeded"],
      "disallowExpiredSuppressions": true
    }
  }
}

Run it in CI:

bash

npx dhal ci

Support report and release check

bash

npx dhal report --output dhal.report.json
npx dhal release-check --target stable --require-build

Review support reports before sharing them. Do not attach secrets, credentials, tokens, or unredacted production traffic to public issues.

Enforcement checklist

Before changing any route to block or strict, confirm:

the exact Dhal version is pinned;
Node.js and framework versions are supported;
schemaVersion is "1";
generated onboarding or OpenAPI changes were reviewed;
test-config, migration check, doctor, and readiness pass;
known-good and malicious replay fixtures pass;
Redis or Valkey is shared for multi-instance deployments;
webhook signing and redaction are configured;
graceful shutdown calls close();
rollback to monitor mode is documented and tested.