@copybook/cli
Commands and flags.
npm i -D @copybook/cliEvery command finds copybook.config.ts by walking up from the current directory. Pass -c, --config <path> to use another file.
init
Creates copybook.config.ts and installs @copybook/core and @copybook/cli with your package manager, which it detects from your lockfile.
| Flag | Description |
|---|---|
--no-install | Only write the config. |
list
Lists every definition with its kind, variant count, and placements.
| Flag | Description |
|---|---|
--json | Print the manifest as JSON. |
--changed | Only definitions whose rendered output changed since --base. |
--base <ref> | The git ref to compare against. Defaults to HEAD. |
snapshot
Writes a rendered snapshot of every definition. It only touches files whose content changed.
| Flag | Description |
|---|---|
--prune | Delete snapshots of definitions that no longer exist. |
check
Validates definitions and compares snapshots. It exits with status 1 on any error. See Snapshots.
| Flag | Description |
|---|---|
--base <ref> | Also warn about ids removed since this ref without an alias. |
test
Parses, typechecks, and runs commands and snippets. See Testing.
| Flag | Description |
|---|---|
-t, --tier <tiers> | Comma-separated tiers: syntax, typecheck, and run. Defaults to syntax,typecheck. |
--only <ids...> | Only these definition ids. |
--changed | Only definitions whose rendered output changed since --base. |
--base <ref> | The git ref to compare against. Defaults to HEAD. |
--reporter <reporter> | pretty, json, or junit. Defaults to pretty. |
-o, --output <file> | Also write the JSON or JUnit report to a file. |
--concurrency <n> | How many cases run at once. |
eval
Gives prompts to coding agents and checks what they did. It refuses to run outside CI unless you pass --unsafe-local. See Evals.
| Flag | Description |
|---|---|
--only <ids...> | Only these prompt ids. |
--agent <names...> | Only these agents. |
--trials <n> | Override each eval's trial count. |
--budget-usd <amount> | Stop starting trials after spending this much. |
--changed | Only prompts whose rendered output changed since --base. |
--base <ref> | The git ref to compare against. Defaults to HEAD. |
--history-dir <dir> | Append results to <dir>/<id>.jsonl, and skip prompts already evaluated. |
--force | Re-run prompts that the history says are unchanged. |
--json | Print the report as JSON. |
--unsafe-local | Allow running outside CI. Agents get full permissions in a directory that isn't isolated from your machine. |
usages
Shows which product files import each definition. Set usage.include in the config. Definitions embedded in a rendered one count as used.
| Flag | Description |
|---|---|
--json | Print the report as JSON. |
report
Prints a Markdown summary of changed definitions for pull request comments. See CI.
| Flag | Description |
|---|---|
--base <ref> | The git ref to compare against. Defaults to origin/main. |
studio
Starts the local Studio UI. See Studio.
| Flag | Description |
|---|---|
-p, --port <port> | The port to listen on. Defaults to 4983. |
--host <host> | The host to bind. Defaults to 127.0.0.1. |
--api-only | Serve only the JSON API. |
Programmatic API
The package also exports the building blocks the commands use: loadProject, buildSnapshots, buildManifest, compareSnapshots, writeSnapshots, changedIds, and fileHistory.
import { buildManifest, buildSnapshots, loadProject } from "@copybook/cli";
const project = await loadProject(process.cwd());
const { snapshots } = buildSnapshots(project);
const manifest = buildManifest(project.definitions, snapshots);