CLI reference

The commands you actually need, which of them are shadcn's, and why opsinjs deliberately ships almost no CLI of its own.

Overview

There is no opsinjs command, and the plan is to keep it that way for as long as possible.

npx shadcn already installs items from a registry, resolves dependencies, previews diffs, decodes preset codes, reads a project's configuration and runs an MCP server. Re-implementing any of that would produce a second tool with the same job, a different set of bugs, and one more thing to keep in step with a specification opsinjs does not own.

This page is therefore mostly a map of somebody else's CLI, annotated with what each command means here. The short list of things opsinjs genuinely needs a tool for is at the bottom, and it is specified rather than built.

Install and add

npx shadcn@latest add https://opsinjs.pensievelabs.org/r/status-pill.json

A full URL is self-contained only for an item that depends on nothing else here. Twenty-one items name their siblings namespaced in registryDependencies, so installing one of those needs an @opsinjs entry in components.json even by URL. The registry overview has the list and the block.

The flags worth knowing:

Flag	What it does	Why it matters here
`--dry-run`	Preview changes without writing	Always worth running first against a registry you do not control
`--diff [path]`	Show the diff for a file	The upgrade path for code you have already edited, covered in Upgrades and diffs
`--view [path]`	Print file contents without installing	Read a health component's source before you accept it
`-o, --overwrite`	Overwrite existing files	Discards your edits. Use with `--diff` first, never alone
`-p, --path <path>`	Install somewhere specific	Overrides the alias resolution from `components.json`
`-a, --all`	Add everything	Never a good idea against opsinjs: it lands all sixty items at once, which is rarely what a project wants

--view deserves emphasis. In a copy-not-dependency model you are accepting source into your repository, and being able to read it before it lands is the main safety property of the whole approach.

Inspect before installing

npx shadcn@latest view @opsinjs/result-card

npx shadcn@latest search @opsinjs -q "range"

npx shadcn@latest docs result-card

search matches against name, title and description, which is why opsinjs writes descriptions in plain English rather than in component vocabulary. The description "a value shown against a reference range" is findable by somebody who does not know the word RangeBar.

Themes and presets

npx shadcn@latest apply <code> --only theme

apply takes a preset code and applies it to an existing project; --only theme and --only font restrict it. The preset command family decodes and resolves codes without applying anything:

npx shadcn@latest preset decode <code>

npx shadcn@latest preset resolve

preset resolve prints the preset your project currently matches, which is the fastest way to answer "what theme is this project actually on". See Preset codes.

Read your own project

npx shadcn@latest info --json

Framework, Tailwind version, aliases, base library, icon library, configured registries and installed components. This is the same call the agent skill makes on activation, and it is a good first move when something installs into an unexpected directory.

Commands to be careful with

migrate rewrites your code in place: icon library, base colour, cn, RTL, Radix. Each subcommand is useful and each is a large diff. Commit first.

The repository's own scripts

If you have cloned or forked opsinjs, these are the commands that matter. They are package.json scripts, not a CLI, and they run under plain Node. The .mts scripts are executed by Node's own type stripping, with no tsx and no ts-node in the tree.

Command	What it does
`pnpm run generate`	Tokens, registry and generated reference pages
`pnpm run contrast`	Measures every token pair with APCA and WCAG 2.2
`pnpm run check`	The three generators in `--check` mode, then `check:generated`, `check:ia`, `check:a11y` and `check:llms`, in that order
`pnpm run check:generated`	Regenerates and fails on a diff
`pnpm run check:ia`	Frontmatter, section outlines, link and reachability assertions
`pnpm run check:a11y`	The accessibility rig's static half, over the component sources
`pnpm run check:llms`	The index and shards against the page tree
`pnpm run check:freshness`	Reports pages past their review SLA. Does not fail the build
`pnpm run evals`	The agent eval suite

check:a11y is the one that reads registry/ rather than content/. It parses each component source as text and fails on a status carried by colour alone, a type size in px, a raw colour literal, an element taking colour from both axes, a banned word, or a class that resolves under the docs chrome and to nothing under /view. It needs no browser and no running server, which is why it sits in the same one-command sweep as the other three. The half that does need a browser runs only in .github/workflows/nightly.yml, and --layout is how you ask for it. That half covers hit area, 1.3x and 200%.

Node 24 or newer is required, and each script starts with a version guard that exits with a readable message rather than a stack trace.

What an opsinjs CLI would be for

Specification only. Nothing is implemented

Planned

opsinjs-cli is described here so that its intent, its refusals and its accessibility bar can be reviewed before a line of it is written. Treat everything below as a proposal under review. Do not generate code against it.

Questions this component has to answer before it ships

Is check-theme a standalone binary or a subcommand of a larger tool?
Should doctor work on any repository, or only one with a components.json?
What is the exit code when a theme passes WCAG 2.2 and fails APCA?

No tracking issue yet.Roadmap Propose a change to this specification

Two jobs npx shadcn genuinely does not do, and they are the only justified scope:

check-theme validates a theme's contrast in CI. Specified in Validating your theme and shipped by @opsinjs/color.

doctor checks the CSS import order, confirms the generated token layer loaded, and confirms no element carries both colour axes. All three are real failure modes that currently have no automated check.

Nothing else. A CLI that duplicates add would be a maintenance liability with no user-visible benefit.

Verify it worked

The CLI sees your project

npx shadcn@latest info prints your configuration. If it prints defaults, it is running from the wrong directory.

A dry run does what you expect

npx shadcn@latest add <url> --dry-run lists the files it would write. Read the list before dropping the flag.

The scripts run

In a fork, pnpm run check should complete. It is the closest thing to a one-command answer to "is this repository consistent".

Troubleshooting

npx uses a stale version. npx clear-npx-cache, then retry. This is also the fix for an MCP server reporting no tools.

A command works globally and not in a monorepo. Use -c, --cwd to point at the package rather than the workspace root.

add wrote nothing and reported success. All sixty ids now carry files, so an empty write points at your components.json rather than at the item. Confirm the aliases resolve to a writable path, check implemented for that name in /r/index.json, and see the registry overview.

A script fails with a syntax error in a .mts file. Node is older than 24 and cannot strip types. Check node --version.

Upgrades and diffs shows --diff in anger.
Preset codes covers encoding, decoding and applying.
MCP server is the same registry, for an assistant.