CLI

search

Search published items. No sign-in needed.

--limit <n>

Maximum results to return.

--json

Print the raw JSON response instead of a list.

--filter <key=value>

Narrow by a facet, repeatable, and comma-separated for several values: --filter frameworks=react.

add

Write an item's files into your project. Repeatable.

--force

Overwrite files that already exist.

--dest <path>

Put the files here, relative to --dir, keeping their layout. Skips the where-to prompt.

--target <id>

Request a delivery target, applied to every item in the command.

--draft

Install the team's draft version. Team members only.

It writes files and stops. Follow-up steps are printed, never run.

item-files

Print an item's files and integration plan as JSON. Writes nothing to disk.

--json

Accepted for stability in scripts. JSON is the only output.

--guides <id>

Also fetch conditional guides by id, from a previous result's guides.index. Repeatable or comma-separated.

print filter-values

List the filter values that currently match published items.

--json

Print the value map as JSON.

print classification-values

List every legal classification value, for writing a manifest. Use print filter-values to build a query.

--json

Print the value map as JSON.

print agent-guide

Print the whole agent workflow, so an agent can learn this lane in one command.

link-items

Open a session and print the link for the human to choose from.

--suggest <team>/<item>

An item to put in front of them. Repeatable.

Suggestions are optional. A session with none opens on a search instead.

await-link-session

Block until the human confirms, then print every pick with its files and integration plan as JSON.

--timeout <seconds>

Give up after this long with exit code 1. By default it waits until the session expires, about 24 hours.

Exit 0 means confirmed, so an agent can branch on it without reading prose.

print authoring-guide

Print the publishing guide: the contract your agent follows to set up and work on a catalog.

init

Set up catalog manifests in this project. Uses published records by default, or saved draft changes with --draft.

--team <slug>

Select one of your account's teams.

--collections <slugs>

Set up manifests for these comma-separated collections.

--whole-catalog

Set up manifests for the team's entire catalog.

--draft

Read saved draft changes, including draft-only records.

--live

Explicitly select the published version (the default).

--force

Allow reinitializing an existing root manifest.

Initial live setup after claiming includes saved readmes and guides referenced by the selected manifests. Catalogs-hosted items also receive prepared item files; self-hosted items receive documentation only. Later setup, draft init, and every pull remain manifest-only. Manage documentation and source code through your project and version control after initial setup.

validate

Check the catalog locally: schema, path safety, references.

status

Compare catalog manifests with the published version. Read-only.

--draft

Compare against saved draft changes.

--live

Explicitly compare against the published version (the default).

publish

Push listings and content up. Never deletes.

--draft

Publish changed items as team-only drafts, without changing live.

--listings-only

Metadata records only. Leave content alone.

--content-only

Content only. Skip metadata.

--restore <type>/<slug>

Re-push a record the platform has deleted. Without it, deleted keys are refused. Repeatable.

promote-draft

Make an item's draft the live version.

discard-draft

Drop an item's draft without changing live.

pull

Update catalog manifests from the published version. Item files stay untouched.

--draft

Pull saved draft manifest changes.

--live

Explicitly pull the published version (the default).

--collections <slugs>

Include missing manifest records in these collections.

--whole-catalog

Include all manifest records for the team.

--fields <a,b>

Take only these fields from the platform copy and keep the rest local. Needs a record address.

--dry-run

Print the plan without writing anything.

remove

Delete a record from the platform. The only command that deletes anything.

--local

Also delete the local manifest record. Refused when it would leave the manifests invalid.

--dry-run

Print the plan without deleting anything.

preview replace

Replace an item's previews with these files, in display order. The first is the featured media.

png, jpeg, webp, gif, mp4, or webm. Originals accepted up to 20 MiB per image and 200 MiB per video; the platform fits and stores them smaller. No count limit.

preview clear

Remove all previews from an item.

preview optimize

Re-encode media on this machine to fit the upload caps. Runs your local ffmpeg.

--out <path>

Write here instead of alongside each source file.

--stage

Compose onto the 16:10 stage, for portrait or simulator recordings.

preview kit

Scaffold an editable capture kit an agent can drive.

--force

Overwrite an existing, non-empty directory.

shadcn convert

Bring a shadcn registry's components into your catalog as items. Files are referenced in place, never copied.

--suffix <text>

Suffix every converted slug, so two parallel registries of the same components can share one catalog.

--split

Write new items as catalog/items/<slug>.item.yaml and add the matching glob.

Re-running syncs new registry changes and never touches what you enriched.

shadcn build

Generate a self-hostable shadcn registry back out of your catalog, using the same emit the hosted endpoint serves.

--out <path>

Output directory. Defaults to public/r.

--target <id>

Include only items declaring this delivery target. Repeatable. Items with no targets always ride along.

--homepage <url>

The homepage written into registry.json.

shadcn diff

Report field-level drift between the catalog and a registry file. Read-only, and exits nonzero on drift.

--target <id>

Compare only items declaring this delivery target.

login

Sign in through the browser.

--token <token>

Store an existing platform token instead.

Sessions are kept per registry, so signing into one never overwrites another.

logout

Forget the stored session for the active registry.

whoami

Show who the platform thinks you are.

mcp

Run the Catalogs MCP server over stdio, for a local or offline setup.

The hosted server on getting started needs none of this.

mcp init

Onboard detected user-level coding harnesses. Merges in place and is safe to re-run.

--client <name>

Which MCP client(s) to configure, repeatable. User: claude, cursor, codex, claude-desktop. Project: claude, cursor, vscode.

--project

Use project scope instead of user-level scope.

--allow-permissions

Allow Catalogs MCP tools in Claude Code without per-call prompts.

--dry-run

Show user-level changes without writing them.

mcp remove

Remove user-level Catalogs MCP setup, or use --project to remove project config entries.

--project

Use project scope instead of user-level scope.

--dry-run

Show user-level changes without writing them.

config

Show where the CLI and editor tools point, and why.

config set

Store a setting. Keys: api-url, site-url, pick-flow.

Rarely needed. The CLI already points at Catalogs, and setting api-url wrong sends you somewhere else.

config unset

Clear a setting and go back to the default.