CLI commands
Every ballmac command and option, generated from the CLI's own help text.
On this page
This page is generated from packages/cli/src/index.ts. To change it, change the source and run pnpm docs:generate.
Run ballmac through npx @ballmac/cli. This page lists every command and option the tool prints in ballmac --help.
pnpm dlx @ballmac/cli <command> [options]npx @ballmac/cli <command> [options]yarn dlx @ballmac/cli <command> [options]bun x @ballmac/cli <command> [options]ballmac add <item…>
Install items with shadcn and start tracking them
| Option | What it does |
|---|---|
--with-tests | also install the tests that ship with the items |
--no-install | do not install the test packages (print them instead) |
ballmac outdated [item…]
Which tracked items have a newer version, and what changed
| Option | What it does |
|---|---|
--json | machine-readable output |
--exit-code | exit 1 when something is behind (for CI) |
ballmac update [item…]
Merge new versions into your copies (your edits are kept)
| Option | What it does |
|---|---|
--dry-run | show what would change and write nothing |
ballmac diff <item>
What you changed since you installed an item
ballmac track [item…]
Start tracking items you installed with plain shadcn
| Option | What it does |
|---|---|
--rebase | declare your files up to date with the latest version |
ballmac check [path…]
Audit your app for what agents and people get wrong: missing states, unlabelled controls, fixed colours, endless motion, overflow on phones
| Option | What it does |
|---|---|
--rules | list the rules and exit |
--format <f> | pretty (default), json or github (annotations for CI) |
--fail-on <level> | error (default), warn or never: when to exit with 1 |
--all | show every finding, not the first few per rule |
--offline | do not read the Ballmac catalogue |
--include-library | also audit components/ui and components/ballmac |
--url <address> | also load a running app in a real browser (axe, overflow, console) |
--routes <a,b> | routes to load with --url (default /) |
ballmac verify <registry>
Score any shadcn registry (a URL, a folder or a registry.json) on what can be checked from its source, and write a badge. Needs TypeScript in this project.
| Option | What it does |
|---|---|
--min-score <n> | exit 1 when the score is below n (for CI) |
--format <f> | pretty (default) or json |
--out <file> | write the scorecard JSON |
--badge <file> | write the "Ballmac Verified" SVG badge |
--item-url <url> | where items live when it is not next to registry.json, e.g. https://acme.com/r/\{name\}.json |
--limit <n> | score only the first n items |
--all | list every item that lost points |
ballmac test [item…]
Run the Ballmac tests installed in this project
ballmac test add <item…>
Install the tests for items that are already installed
Global options
| Option | What it does |
|---|---|
--cwd <dir> | Project folder (default: the current folder) |
-v, --version | Print the version |
-h, --help | Print this help |
Environment variables
| Variable | What it does |
|---|---|
BALLMAC_UI_URL | Registry to read (default https://ui.ballmac.com) |
BALLMAC_LICENSE_KEY | Your Ballmac UI Pro key (env or .env.local); needed for Pro items |
BALLMAC_SHADCN | How to run shadcn, e.g. "pnpm dlx shadcn@latest" (default: your local copy, else the package manager's runner) |