@krazdesign/cli

The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.

Run it one-off with the scoped package (works whether or not it's installed):

npx @krazdesign/cli --help
npx @krazdesign/cli search button
npx @krazdesign/cli component Button
npx @krazdesign/cli docs tokens
npx @krazdesign/cli docs migration
npx @krazdesign/cli template --list

Once it's a project dependency (npm install -D @krazdesign/cli), drop the scope and use the shorter kraz — e.g. npx kraz component Button or pnpm exec kraz component Button. Bare kraz resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.

Finding things: kraz search

When you don't know whether what you need is a component, a hook, a docs topic, or a template, search across all of them at once. Results are ranked by relevance (name and keyword matches outrank incidental prose mentions, with fuzzy matching for typos) and tagged with their domain plus the follow-up command to run:

$ kraz search button

Results for "button" (20):

  [component]  Button
               Button triggers an action when clicked. Use it for form submissions…
               → kraz component Button

  [component]  IconButton
               A button that shows only an icon with no visible text…
               → kraz component IconButton

  [hook]       useClickableContainer
               Makes a container element clickable while preserving nested…
               → kraz hook useClickableContainer

  [template]   Banner — Collapsible
               Combine an action button, dismiss control, and expandable detail area…
               → kraz template BannerCollapsibleContent

(The CLI prints the follow-up commands with your actual runner — npx kraz … when installed, or npx @krazdesign/cli … when run one-off.)

Options:

• --type <component|hook|doc|template>: restrict to a single domain
• --limit <n>: cap the number of results (default 20)
• --detail: include the import path and the match reason/score
• --json: typed { type: 'search', data: { query, results } } envelope

Commands

| Command | Description | | ---------------------- | ----------------------------------------------------------------------------- | | blog | Read the Kraz blog from the published feed | | build | Build a page: composition kit for an idea, or the workflow playbook (no args) | | component | List components or print component docs | | discover | Discover external packages and components | | docs | Print reference docs | | doctor | Diagnose your XDS setup and report problems with fixes | | hook | List hooks or print hook docs | | init | Initialize the design system in your project | | layout | Generate XDS layouts from compressed expressions (XLE/XLO) | | search | Search components, hooks, docs, and templates in one ranked list | | swizzle | Copy component source for customization | | template | Inject a page or block template | | theme | Theme tools: build, export, and manage themes | | upgrade | Run codemods to migrate between versions | | validate-integration | Validate an Kraz integration package (manifest + contributions) |

Global options

These flags work with any command:

• --json: Output as typed JSON envelope: { type, data } (errors: { error, code, suggestions? })
• --detail <level>: Detail level for list views, increasing in size: brief (names only, default for --list) < compact (names + 1-line descriptions) < full (full docs per entry). Single-item views default to full.
• --zh: Output docs in Chinese Simplified
• --dense: Compressed format (token-efficient, useful for AI agents)
• --lang <locale>: Language/format shorthand (en, zh, dense)

JSON API

Every command supports --json for machine-readable output. Responses are typed envelopes:

{"type": "component.detail", "data": {"name": "Button", ...}}

Errors:

{
  "error": "No component named \"Buttn\"",
  "code": "ERR_UNKNOWN_COMPONENT",
  "suggestions": [{"name": "Button", "reason": "similar name"}]
}

The code field is a stable, machine-readable identifier. Branch on it, never on the human-readable error string, which changes freely as we improve wording. Every error envelope carries a code (falling back to ERR_UNKNOWN when no more specific code applies). The same code is exposed on thrown KrazError instances from the programmatic API, so both surfaces agree.

Codes are append-only: once shipped, a code's meaning never changes and a code is never removed. New error conditions get new codes.

import {isError} from '@krazdesign/cli/json';

const result = parseResponse(raw);
if (isError(result)) {
  switch (result.code) {
    case 'ERR_UNKNOWN_COMPONENT':
      // suggest the closest match
      break;
    case 'ERR_CORE_NOT_FOUND':
      // prompt the user to install @krazdesign/core
      break;
    default:
      console.error(result.error);
  }
}

Error codes

| Code | Meaning | | ------------------------- | ------------------------------------------------------------------------------------- | | ERR_UNKNOWN | Fallback for any error without a more specific code. | | ERR_UNKNOWN_COMMAND | A top-level command name was not recognized (e.g. kraz bogus). | | ERR_UNKNOWN_SUBCOMMAND | A subcommand under a command group was not recognized (e.g. kraz theme bogus). | | ERR_INVALID_OPTION | An unknown flag/option was passed (Commander unknownOption). | | ERR_INVALID_ARGUMENT | An option/argument had a value Commander's parser rejected. | | ERR_MISSING_ARGUMENT | A required positional argument was omitted (Commander missingArgument). | | ERR_INVALID_LANG | --lang was given a value outside its choices (en, zh, dense). | | ERR_INVALID_DETAIL | --detail was given a value outside its choices (full, compact, brief). | | ERR_NODE_VERSION | The running Node.js version is below the supported minimum. | | ERR_CORE_NOT_FOUND | @krazdesign/core could not be located (not installed / not in a monorepo). | | ERR_UNKNOWN_COMPONENT | No component matched the requested name. | | ERR_UNKNOWN_HOOK | No hook matched the requested name. | | ERR_UNKNOWN_TOPIC | No docs topic matched the requested name. | | ERR_UNKNOWN_SECTION | A docs topic exists but the requested section within it does not. | | ERR_UNKNOWN_CATEGORY | A --category filter value did not match any known category. | | ERR_UNKNOWN_TEMPLATE | No template matched the requested name. | | ERR_AMBIGUOUS_TEMPLATE | A template id matched more than one template (narrow with --type/--package). | | ERR_AMBIGUOUS_COMPONENT | A component name is owned by more than one package (narrow with --package). | | ERR_UNKNOWN_THEME | No theme matched the requested slug (theme add). | | ERR_UNKNOWN_PACKAGE | No package matched the requested name (discover). | | ERR_UNKNOWN_AGENT | An unrecognized --agent value was passed to agent-docs/init. | | ERR_UNKNOWN_FEATURE | An unrecognized --features value was passed to init. | | ERR_UNKNOWN_CODEMOD | A --codemod value did not match any registered codemod (upgrade). | | ERR_CODEMOD_FAILED | One or more codemods failed during an upgrade run. | | ERR_NOT_FOUND | A generic discover/lookup query matched nothing in any package. | | ERR_NO_DOC | A component exists but has no typed .doc.mjs file. | | ERR_NO_SHOWCASE | No showcase exists for the requested component. | | ERR_NO_SOURCE | No source file could be located for the requested component/template. | | ERR_INVALID_DOC | A component's docs failed validation (malformed .doc.mjs). | | ERR_FILE_NOT_FOUND | A required input file did not exist. | | ERR_FILE_EXISTS | Refused to overwrite an existing file in non-interactive mode. | | ERR_PATH_TRAVERSAL | A path escaped its allowed root, or a name contained traversal markers. | | ERR_WRITE_FAILED | Writing output files failed (and was rolled back). | | ERR_THEME_INVALID | A theme definition was missing a required property (e.g. name). | | ERR_THEME_LOAD | A theme file could not be loaded / parsed into a defineTheme result. | | ERR_VERSION_DETECT | The current @krazdesign/core version could not be detected. | | ERR_INVALID_VERSION | A --from/--to value was not a valid semver string. | | ERR_DEP_MISSING | A required external dependency (e.g. jscodeshift) is missing. | | ERR_GH_CLI | GitHub CLI (gh) is not installed or not authenticated. | | ERR_UNKNOWN_POST | No blog post matched the requested slug in the feed. | | ERR_FETCH_FAILED | A network fetch (RSS feed or post text) failed. | | ERR_LAYOUT_PARSE | A layout expression failed to parse (syntax error, with line/col). | | ERR_LAYOUT_INVALID | A layout expression parsed but failed validation (unknown component/prop/enum/block). |

Capability manifest (agent discovery)

Agents don't have to scrape --help to learn the CLI. A single call returns a self-describing manifest: every command, its arguments, flags (with types, choices, and defaults), whether it supports --json, and the response type discriminators each command can emit. Think of it as an OpenAPI spec for the CLI.

kraz manifest --json        # dedicated surface — type: "manifest"
kraz --json                 # bare invocation — embeds the same payload under data.manifest

Shape:

{
  "apiVersion": 1,
  "type": "manifest",
  "data": {
    "name": "kraz",
    "version": "0.0.14",
    "description": "Design system CLI — components, themes, and tooling",
    "globalOptions": [
      {
        "flag": "--json",
        "type": "boolean",
        "description": "Output as typed JSON…",
      },
      {
        "flag": "--lang <locale>",
        "type": "enum",
        "choices": ["en", "zh", "dense"],
      },
      {
        "flag": "--detail <level>",
        "type": "enum",
        "choices": ["full", "compact", "brief"],
        "default": "full",
      },
    ],
    "commands": [
      {
        "name": "component",
        "description": "List components or print component docs",
        "arguments": [
          {
            "name": "name",
            "required": false,
            "variadic": false,
            "description": "",
          },
        ],
        "options": [
          {
            "flag": "--props",
            "type": "boolean",
            "description": "Print only the props table",
          },
        ],
        "json": true,
        "responseTypes": [
          "component.list",
          "component.detail",
          "component.detail.props",
          "…",
        ],
        "examples": ["kraz component Button --props --json"],
      },
      // …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
    ],
    "jsonSupported": ["component", "docs", "…"],
    "responseTypes": {
      "component": ["component.list", "…"],
      "theme build": ["theme.build"],
    },
  },
}

The manifest is derived from Commander metadata (commands, arguments, options) so it can't drift from the real command definitions. The two facts Commander doesn't track (--json support and emitted response types) are layered on from the JSON_SUPPORTED allowlist and a small declarative RESPONSE_TYPES map in src/lib/manifest.mjs, guarded by a drift test (manifest.test.mjs) so adding a command without describing it fails CI.

Backwards-compat: the bare kraz --json envelope keeps type: "help" and its original shallow fields (name, version, commands as a string[] of names, jsonSupported); the full structured manifest is additive under data.manifest. For the standalone manifest envelope (type: "manifest"), use kraz manifest --json.

Programmatic API

The same logic that powers kraz --json is available as importable, type-safe functions:

import {
  component,
  docs,
  discover,
  template,
  hook,
  search,
  KrazError,
} from '@krazdesign/cli/api';

// Same result as: kraz --json component Button
const btn = await component('Button');
btn.type; // 'component.detail'
btn.data.name; // 'Button' (typed as ComponentDoc)

// Same result as: kraz --json component --list
const list = await component(undefined, {list: true});
list.data; // Record<string, string[]>

// Same result as: kraz --json docs principles
const principles = await docs('principles');
principles.data.title; // 'Principles'

// Same result as: kraz --json hook useMediaQuery
const useMediaQuery = await hook('useMediaQuery');
useMediaQuery.data.params; // typed as HookParamDoc[]

// Errors throw KrazError with a stable .code and optional .suggestions
try {
  await component('Buttn');
} catch (e) {
  e.message; // 'No component named "Buttn"'
  e.code; // 'ERR_UNKNOWN_COMPONENT' (stable; branch on this)
  e.suggestions; // [{ name: 'Button', reason: 'similar name' }]
}

The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that @krazdesign/cli/api and kraz --json always return identical data.

Consumer utilities

If you're spawning the CLI as a subprocess rather than importing the API directly:

import {parseResponse, isError} from '@krazdesign/cli/json';
import type {
  ComponentDetailResponse,
  ComponentListResponse,
  DocsListResponse,
  // ...import the response types for the commands you consume
} from '@krazdesign/cli/json';

// parseResponse returns the structural { type, data, meta? } envelope; `data`
// is `unknown` until you narrow it. Reconstruct the union you care about from
// the per-command response types, then narrow on `type`:
type MyResponse =
  ComponentDetailResponse | ComponentListResponse | DocsListResponse;

const result = parseResponse(stdout);
if (isError(result)) {
  console.error(result.error);
} else {
  const r = result as MyResponse;
  switch (r.type) {
    case 'component.detail':
      r.data.name; // narrowed to ComponentDoc
      break;
  }
}

Prefer narrowing at the call site? Wrap assertResponse (which throws on error/mismatch) with your reconstructed union:

import {assertResponse} from '@krazdesign/cli/json';
import type {ComponentDetailResponse} from '@krazdesign/cli/json';

type MyResponse = ComponentDetailResponse; /* | ...others */

function assertTyped<T extends MyResponse['type']>(raw: unknown, type: T) {
  return assertResponse(raw, type) as Extract<MyResponse, {type: T}>;
}

const detail = assertTyped(stdout, 'component.detail');
detail.data.name; // narrowed

Migration (removed in the structural-jsonOut release): the central CLIAnyResponse, CLIResponseType, and CLIResponseDataMap exports were removed. parseResponse / assertResponse no longer auto-narrow .data. Rebuild the union from the individual *Response types as shown above — they are all still exported from @krazdesign/cli/json.

Type discriminators

Every response has a type discriminant. The full set is below (generated from the manifest). Each command's types are also listed in kraz manifest --json, and the matching *Response TypeScript types (e.g. ComponentDetailResponse) are exported from @krazdesign/cli/json. Errors use CLIError, and unsupported commands use CLIUnsupportedError.

| Type | What data carries | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | component.list | The component catalog grouped by category: detail (the level: names | compact | full) and components, the grouped map of names+package, brief entries, or a full ComponentDoc per entry. | | component.detail | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available). | | component.detail.props | Just one component's props table (ComponentPropDoc[]). | | component.detail.source | One component's source file, as {component, source}. | | component.detail.showcase | One component's showcase example, as {component, aspectRatio, source}. | | component.detail.blocks | One component's example blocks, as {component, showcase, examples, related} of BlockEntry. | | docs.list | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order. | | docs.detail | One topic's full ReferenceDoc, with token-ref blocks inlined. | | docs.detail.section | A single ReferenceSection of a topic: the first whose title contains the section query. | | blog.list | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL. | | blog.detail | One post's metadata plus the feed URL and the post's full plaintext body. | | discover.list | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered". | | discover.detail | A single external package entry, for an @scope/name query. | | discover.detail.doc | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component. | | discover.search | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components. | | search | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant). | | build.help | A marker (playbook: true) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given. | | build.kit | The grouped composition kit: echoed query, hasResults/directMatch flags, the closest page templates, drop-in block patterns, idea-specific components/hooks, and the always-on frame + foundation component-name arrays. | | swizzle.list | The names of swizzlable components discoverable from cwd's @krazdesign/core. | | swizzle.copy | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note. | | template.list | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags. | | template.show | The resolved template's raw source plus its description, kind, and the component names it composes. | | template.skeleton | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes. | | template.copy | A scaffold receipt: template id, output directory, written file name, and file count. | | template.cdn | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Kraz version every CDN URL was pinned to, whether it was written, and the reason it was not — exists when a file was already there, which is a success. | | hook.list | The hook catalog grouped by category: detail (the level: names | compact | full) and components, the grouped map of hook names, brief entries, or a full HookDoc per entry. | | hook.detail | One hook's full authored HookDoc. | | hook.detail.params | Just one hook's parameters table (HookParamDoc[]). | | theme.build | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings. | | theme.build.check | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing | outdated}), and the full list of checked paths. Writes nothing. | | theme.build.batch | Several themes built in one invocation: count plus one {file, receipt} per theme in argument order, where receipt is that theme's theme.build (or theme.build.check) envelope, or null when it produced no CSS. | | theme.list | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag. | | theme.add | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written. | | theme.template | A write receipt for the annotated theme template: the path (relative to cwd), whether it was written, and the reason it was not — exists when a file was already there, which is a success. | | upgrade.list | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything. | | upgrade.status | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary. | | upgrade.run | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors. | | manifest | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index. | | doctor | The health-check report: checks (each with id, label, status: pass | warn | fail | info, a message, and a fix when not passing) plus a summary of counts per status. | | integration.validate | The validation result: the package name and version (both null when no local manifest is found) plus issues, an KrazIntegrationIssue[] of {code, severity: warning | error, message}. | | layout.expand | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written). | | layout.check | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline). | | layout.grammar | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry. |

Doctor

kraz doctor runs a series of health checks against your project and environment and reports PASS / WARN / FAIL for each, with an actionable fix for anything that isn't passing. It's read-only; it never installs or mutates anything, so it's safe to run anywhere, including CI.

$ kraz doctor
kraz doctor — diagnosing your setup

  ✓ Node.js version
      Node v22.13.0 meets the minimum (>=22.13.0).
  ✓ @krazdesign/core installed
      @krazdesign/core resolved (v0.0.14).
  ✓ @krazdesign/core <-> @krazdesign/cli alignment
      @krazdesign/core v0.0.14 is in step with @krazdesign/cli v0.0.14.
  ⚠ Theme packages
      No @krazdesign/theme-* packages are installed.
      → fix: Install a theme, e.g. `npm install @krazdesign/theme-neutral`, then import its CSS or set kraz.theme.
  ℹ kraz.config.mjs
      No kraz.config.mjs found — using defaults.
  ℹ AI agent docs
      No agent docs (CLAUDE.md / AGENTS.md / .cursorrules) found.
      → fix: Generate agent docs with `kraz init --features agents`.
  ✓ @krazdesign/core peer dependencies
      All peer dependencies satisfied (react, react-dom).
  ℹ Package manager
      Detected package manager: yarn.

Summary: 4 passed, 1 warning, 0 failures, 3 info

No failures — but review the ⚠ warnings above when you can.

Checks

| Check | Status it can return | What it verifies | | -------------------------- | -------------------- | ------------------------------------------------------------------ | | Node.js version | pass / fail | Running Node meets the CLI's minimum | | @krazdesign/core installed | pass / fail | @krazdesign/core is resolvable from the project | | Version alignment | pass / warn / info | Installed @krazdesign/core is in step with @krazdesign/cli | | Theme packages | pass / warn | An @krazdesign/theme-* package is installed and a theme is wired | | kraz.config.mjs | pass / fail / info | Config (if present) loads cleanly with a valid shape | | AI agent docs | pass / warn / info | Agent docs exist and contain the Kraz section markers | | Peer dependencies | pass / warn / info | @krazdesign/core's peer deps (react, …) are installed | | Package manager | info | Reports the detected package manager |

CI gate

The exit code is the contract: kraz doctor exits 0 when there are no failures (warnings are fine) and 1 when any check fails. That makes it usable directly as a CI step:

- run: npx @krazdesign/cli doctor

Use --json for a structured envelope ({ apiVersion, type: "doctor", data: { checks, summary } }) that AI agents and scripts can parse.

Configuration

The CLI reads an optional kraz.config.{ts,mjs,js} from your project root (a sibling of package.json). Every field is optional; with no config file the CLI runs on defaults.

export default {
  integrations: ['@acme/kraz-widgets'],
  issuesUrl: 'https://github.com/your-org/your-repo/issues',
};

There is no factory: write a plain object. For editor autocomplete and type-checking, annotate it with the KrazConfig type exported from @krazdesign/cli/authoring.

| Field | Type | Purpose | | ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- | | integrations | string[] | Integration package names to load (see Integrations). | | issuesUrl | string | Where "report an issue" links point for your project. Defaults to the core issue tracker. | | hooks.postCodemod | PostCodemodHook[] | Commands to run after kraz upgrade applies codemods (e.g. reinstall, rebuild, reformat). | | experimental.xle.components | Record<string, XleComponent> | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |

The config is validated against a strict schema when the CLI loads it, so an unknown field is a hard error rather than a silent no-op. kraz doctor reports whether the config loads cleanly.

Core codemod authoring

Core codemods live under packages/cli/assets/codemods/transforms/. Released codemods are grouped by the target package version (v0.3.0, v0.3.1, ...), which is the version that first contains the breaking change.

Do not guess that version in ordinary feature PRs. Add new codemods to packages/cli/assets/codemods/transforms/next/ instead:

• put transform modules and tests in transforms/next/;
• maintain transforms/next/index.mjs with the run order for the staged transforms;
• leave transforms/next/README.md in place; it documents the staging area and is never promoted.

During the Version Packages PR, pnpm version-packages runs scripts/promote-codemod-next.mjs after changeset version. The script copies all staged entries except the README into transforms/v<new-core-version>/, registers that version in packages/cli/assets/codemods/registry.mjs, and clears the promoted files from next.

This mirrors Changesets: feature PRs stage migration work without knowing the future release number; the release PR assigns the exact version.

Integrations

An integration is any npm package that contributes its own components, templates, and upgrade codemods to Kraz. The CLI surfaces them next to core's, through the same commands, so a consumer can kraz component, kraz template, and kraz upgrade across core and every integration uniformly. Use it to ship a first-party add-on, publish a third-party component library, or share an internal design-system package across apps.

The system runs on two files, each with a small typed API:

| File | Written by | Role | | ------------------------------ | ---------- | ----------------------------------------- | | kraz.config.{ts,mjs,js} | Consumer | Lists which integration packages to load. | | kraz.integration.{ts,mjs,js} | Author | Declares what a package contributes. |

The consumer side is the integrations field of kraz.config. The author side is the integration manifest below.

The integration manifest

A package becomes an integration by exporting a manifest from kraz.integration.{ts,mjs,js} at its root (a sibling of package.json). The manifest points at where each kind of contribution lives; identity (name, version) comes from package.json, not the manifest.

export default {
  components: './components',
  templates: './templates',
  codemods: './codemods',
  issuesUrl: 'https://github.com/acme/widgets/issues',
};

| Field | Type | Purpose | | ------------ | -------- | --------------------------------------------------------------------- | | components | string | Directory holding the package's components and their .doc.* files. | | templates | string | Directory holding the package's page/block templates. | | codemods | string | Directory holding upgrade codemods run by kraz upgrade. | | issuesUrl | string | Where "report an issue" links for this package's contributions point. |

Every field is optional; declare only the roots the package ships. There is no factory: write a plain object, and annotate it with the KrazIntegration type from @krazdesign/cli/authoring for editor autocomplete and type-checking.

How it works

Every command loads the consumer's kraz.config, resolves each listed integration's manifest from node_modules, and discovers its contributions. Everything is validated against one strict schema at the load boundary, so the CLI presents core and integration contributions through a single, uniform surface.

Discovery is resilient: a broken or misconfigured integration is skipped with a one-line warning on stderr instead of crashing the CLI, and it never corrupts a --json envelope. To inspect problems, run kraz validate-integration <package> for a detailed report on one package, or kraz doctor for an overall health check.

For the full authoring walkthrough (component doc format, template packaging and exports requirements, and codemod authoring), see the guide:

kraz docs cli-integrations