Gesso Command Line Interface

The Gesso CLI helps people and coding agents create prototypes, add Gesso to existing Next.js projects, query versioned design-system information, and check project health.

Registry authentication

Acromedia packages require a personal GitLab access token. Prefer a user-global ~/.npmrc with an environment-variable token reference so authentication is available to every project. A project .npmrc is also inspected, before the home file, but it is not copied into a prototype created elsewhere.

Never share or commit a token. See the canonical registry authentication guide for configuration, precedence, placeholder and unreadable-file behavior, and troubleshooting.

Start a standalone prototype

pnpm dlx @acromedia/gesso-cli create my-prototype
cd my-prototype
pnpm install
pnpm dev

The runtime requires create <dir>. The target must be absent or empty. The command creates a standalone Next.js App Router prototype with exact Gesso and CLI version pins, wired providers, and agent instructions. It attempts to install the gesso-react skill in each supported skill directory and reports each outcome; one failed path does not fail the command when another path installs the skill or is safely skipped, while failure in every directory does.

Authentication available only through the source project's .npmrc does not follow the generated project. Ensure pnpm install can use home or target-local configuration. See gesso create for target safeguards and recovery.

Initialize an existing Next.js project

From the project root:

pnpm dlx @acromedia/gesso-cli init
pnpm install
pnpm gesso health

init requires next in package.json and rejects the project when that prerequisite is missing; it does not add Next.js. When a Gesso or CLI declaration is missing, it adds the exact targeted @acromedia/gesso version to dependencies or the running @acromedia/gesso-cli version to devDependencies, so it can change package.json.

It conditionally creates src/theme.ts and an App Router providers boundary, but never edits the App Router layout or Pages Router custom App. Existing generated-file paths are not overwritten. AGENTS.md and CLAUDE.md are created only when neither exists; if either exists, both remain untouched.

The command attempts each supported skill directory and reports whether its bundled skill was installed, refreshed, or skipped. Current skills and skills whose metadata.author is not acromedia are left unchanged. One failed path does not fail init when another path installs the skill or is safely skipped; only all-directory failure makes the command fail. A fully initialized project reports a no-op, although manual provider-wiring instructions can still be printed. See gesso init for router-specific behavior and failure semantics.

Agent commands

Run an installed command as pnpm gesso <command>.

Command	What it does
pnpm gesso agent	Show the agent-facing Gesso overview and next steps.
pnpm gesso rules [topic]	List rule topics or print one rule.
pnpm gesso components [--category <category>]	List components, optionally filtered by category.
pnpm gesso component <Name> [--full]	Show a component's import, props, and usage.
pnpm gesso patterns [--category <category>]	List patterns, optionally filtered by category.
pnpm gesso pattern <Name> [--full]	Show a pattern's path, verified import status, props, and usage.
pnpm gesso layouts [--category <category>]	List layouts, optionally filtered by category.
pnpm gesso layout <Name> [--full]	Show a layout's path, verified import status, props, and usage.
pnpm gesso search --query <query>	Search the catalog across component, pattern, and layout names, paths, descriptions, and prop names.
pnpm gesso tokens [--group <group>]	List token groups or one group's values.
pnpm gesso create <dir>	Create a standalone prototype.
pnpm gesso init	Add Gesso and agent support to an existing project.
pnpm gesso health	Run eight setup checks and print a fix for every failure.

The full agent command reference documents matching, TOON output, errors, and recovery.

Health

pnpm gesso health checks registry authentication, installed Gesso, dependency placement, bundled-documentation version matching, provider wiring, the development script, agent instructions, and configuration deprecations. It exits with status 1 if any check fails. Apply each row's fix and rerun it.

The version check compares installed @acromedia/gesso with the Gesso version targeted by the CLI's bundled catalog documentation, not with the CLI package version. See the health reference.