CLI

🔄 Auto-generated mirror. Canonical source: docs/cli.md. Edit there — changes here are overwritten by CI.

CLI

Nav: Quick start · Writing cases · Hierarchy · Tweaks · Theming · Documentation panel · Writing placard docs · Testing · CLI · AI agents · Configuration

The CLI takes a package directory (<pkgDir>) — the directory containing the display-case.config.ts. It defaults to the current directory when omitted.

display-case <pkgDir> [--port=N]
display-case <pkgDir> --print-manifest
display-case check <pkgDir> [--tokens] [--a11y] [--visual] [--update] [--port=N]
display-case init <pkgDir> [--agent=claude] [--with-visual] [--dry-run] [--json]
display-case uninstall <pkgDir> [--agent=claude] [--dry-run] [--json]

init / uninstall scaffold (or remove) Display Case's AI-agent integration — a launch entry, the bundled skills, and an agent-guide pointer. See AI agents → Scaffolding integration.

Display Case requires Bun. Invoke it with bunx:

bunx @awarebydefault/display-case <pkgDir>          # dev server
bunx @awarebydefault/display-case check <pkgDir>    # checks

For day-to-day use, add npm scripts and run them via bun run:

// package.json
{
  "scripts": {
    "display-case": "display-case .",
    "display-case:check": "display-case check ."
  }
}

bun run display-case          # dev server
bun run display-case:check    # checks

display-case <pkgDir> — dev server

Discovers cases, bundles them with Bun, and serves the browsing UI. The server URL is printed on start, and it rebuilds automatically when a *.case.tsx or *.placard.md file under src/ changes (refresh to pick up — there is no in-page HMR).

Flag	Default	Description
--port=N	3100	Port to serve on.

display-case .
display-case . --port=4000

The served endpoints are documented in AI agents.

display-case <pkgDir> --print-manifest

Builds the manifest once, prints it to stdout as formatted JSON, and exits 0. No server is started. This is the recommended way for a machine reader to enumerate everything available.

display-case . --print-manifest

Each component entry also carries its resolved information-architecture group (a path; [] for the building-block kit and default-group surfaces), and the top level reports modes (the present browse modes, e.g. ["primer","components","exhibits"]), the resolved landing mode, and groups (the Exhibits group tree). A surface's in-app address uses the /e/ prefix and a kit case the /c/ prefix; renderUrl is unified.

See AI agents for the manifest shape and how to use it.

display-case check <pkgDir> — structure + token + a11y + visual checks

Runs these phases: structure best-practice rules (static; no browser), design-token conformance (a static var() parse, no browser), SSR pre-render safety, a bundle-graph budget (--graph), headless accessibility (axe-core), and visual-regression (pixel diff). The a11y and visual phases run over every case in both light and dark themes; structure and tokens need neither a browser nor the server. Exits 0 when everything passes, 1 when any error-severity finding is produced.

The a11y phase prints each violation's affected nodes (for colour-contrast, the failing element and the measured-vs-required pair) and writes the full run to .display-case/a11y/last-check.json for reading without re-running — see Testing → Accessibility.

Flag	Default	Description
--structure	—	Run the static best-practice rules (coverage, levels, primer, setup, composition…). See Testing.
--tokens	—	Run design-token conformance (static; no browser). See Testing.
--ssr	—	Server-render every case and fail on any that can't pre-render.
--graph	—	Measure each component's real bundled module graph and warn on an over-budget graph or a barrel import. Builds each component in isolation, so it is not part of the fast --structure --tokens --ssr gate; it runs in a no-flag full check. Tune budgets with check.graphBudget.
--a11y	—	Run accessibility checks.
--visual	—	Run visual-regression checks.
--update	off	(Re)record visual baselines from the current renders.
--strict	off	Treat structure and graph warnings as errors for this run.
--only=ids	—	Scope the render phases (a11y/visual) to these component ids or globs (comma-separated).
--changed[=ref]	—	Scope the render phases to components a change touched since ref (default the base branch, or DISPLAY_CASE_BASE_REF).
--port=N	ephemeral	Port for the internal server the checks drive.

Default behavior: if no phase flag is given, all phases run — except any a config opts out via check.defaultPhases. Pass one or more phase flags to narrow to just those phases; an explicit flag always runs that phase regardless of config.

Change-scoping the render checks. --only / --changed restrict the (slow, browser-backed) a11y and visual phases to a subset of components — the static phases are unaffected. With --changed, a component is in scope when a changed file is in its import closure; a change to a globally-applied stylesheet or the shared render path scopes to all components, and a change with no render inputs (docs, tests) scopes to none (the render phases pass without launching a browser). This is what the CI a11y/visual jobs use. See Testing → Change-scoped checks.

--ssr and a split React install. The SSR phase renders each case in-process, so it needs Display Case and your cases to resolve one React. If they don't — most often bunx @awarebydefault/display-case run from a directory that doesn't depend on the tool, which pulls a second React into a temp prefix — every hook-using case throws an identical resolveDispatcher() … useState and used to be misreported as ~N "move browser APIs into effects/handlers, or declare browserOnly" findings. The check now detects that once and reports a single environment fault that names both React copies (path + version), classifies the cause, and prescribes the fix (typically: add @awarebydefault/display-case to the package that provides your cases' React, or run the workspace-installed binary instead of bunx). These are not component bugs — don't edit cases or add browserOnly to silence them.

display-case check .                       # all phases (minus config opt-outs)
display-case check . --structure           # best-practice rules only (fast, no browser)
display-case check . --tokens              # token conformance only (fast, no browser)
display-case check . --a11y                # a11y only
display-case check . --structure --strict  # structure rules, warnings fail the run
display-case check . --visual --update     # record/refresh visual baselines
display-case check . --a11y --only=button  # a11y for one component
display-case check . --a11y --visual --changed=origin/main  # only what this branch touched

Full details — the structure rules and their escape hatches, baselines, diff outputs, exit codes — are in Testing. Per-rule severity and enable/disable live in Configuration.