Agent command reference

These read-only commands serve versioned Gesso information to coding agents. Run them from an installed project with pnpm gesso. Successful output ends with one next: recovery or workflow instruction and exits 0. Command-handler and runtime result errors begin with error:, end with next:, and exit 1. Commander parse errors do not necessarily use that format; for example, a present --query without its value can write to stderr and exit 1 without next:. Structured lists use TOON (Token-Oriented Object Notation).

Agent

Syntax: pnpm gesso agent

There are no arguments or options. The command reports the CLI version, whether installed Gesso matches the version targeted by bundled documentation, component/pattern/layout counts and category counts, prototyping rules, library-development topics, and suggested catalog commands. Rule and help lists use TOON.

pnpm gesso agent

The default next step is gesso rules layout. A missing Gesso installation is reported in the overview with create/init guidance rather than making this command fail. If loading the bundled catalog index fails with a filesystem access error, restore the read access identified by the error and retry. For other missing, unreadable, malformed, or invalid load failures, reinstall @acromedia/gesso-cli and retry.

Rules

Syntax: pnpm gesso rules [topic]

With no topic, the command returns a TOON list of all topics and summaries. Topics are exact and case-sensitive:

• layout
• theming
• architecture
• component-creation
• project-context
• nextjs-link

pnpm gesso rules
pnpm gesso rules layout

A selected topic prints its Markdown rule file. There are no options and no default topic. An unknown or differently cased topic fails and lists valid topics; use pnpm gesso rules to recover. Missing rules files require reinstalling the CLI. For an unreadable file, restore the access identified in the error and retry.

Catalog list commands

The plural commands list one catalog kind at a time. Their optional --category value uses an exact, case-insensitive match; it is not a substring filter. There is no default category. A category with no match fails and prints that kind's available categories so you can copy one or rerun without the filter.

Components

Syntax: pnpm gesso components [--category <category>]

Returns TOON rows with name, category, and a description shortened to 100 characters.

pnpm gesso components
pnpm gesso components --category inputs

A successful result points to pnpm gesso component <Name>.

Patterns

Syntax: pnpm gesso patterns [--category <category>]

Returns TOON rows with name, category, Storybook path, and a description shortened to 100 characters. Keep the displayed path: it can qualify a pattern whose leaf name is ambiguous.

pnpm gesso patterns
pnpm gesso patterns --category commerce

A successful result points to pnpm gesso pattern <Name>.

Layouts

Syntax: pnpm gesso layouts [--category <category>]

Returns TOON rows with name, category, Storybook path, and a description shortened to 100 characters. Keep the displayed path: it can qualify a layout whose leaf name is ambiguous.

pnpm gesso layouts
pnpm gesso layouts --category account

A successful result points to pnpm gesso layout <Name>.

Search

Syntax: pnpm gesso search --query <query>

--query is required and must be nonempty. Matching is a case-insensitive substring search across component, pattern, and layout names, Storybook paths, descriptions, and prop names. Results are TOON rows containing kind, name, category, path, matched fields, and a description shortened to 100 characters.

pnpm gesso search --query button
pnpm gesso search --query account

There is no default query. Omitting it or passing an empty value fails with an example query. Zero matches also fail; for longer searches the recovery suggests a shorter query, otherwise it suggests browsing pnpm gesso components, pnpm gesso patterns, or pnpm gesso layouts. Successful output points to the component, pattern, and layout detail commands.

Tokens

Syntax: pnpm gesso tokens [--group <group>]

Without --group, the command returns TOON rows containing each token-group name and token count. With the option, it returns all values in one group. Group matching is exact and case-insensitive.

pnpm gesso tokens
pnpm gesso tokens --group colors

There is no default group. A group with no exact match fails and lists valid groups; recover with pnpm gesso tokens and copy a listed name. Group details point to the theming rules before overriding tokens.

Catalog detail commands

The singular commands require an exact, case-insensitive identifier. They accept the catalog name or title, slug, full Storybook path, or the path without its leading Components/, Patterns/, or Layouts/ segment. Qualified identifiers are checked before leaf names. If a leaf name is ambiguous, the command fails with sorted candidate paths; rerun it with one of those paths.

Detail output includes a heading and description, TOON props, and usage examples. Prop type and description fields are shortened for readability. Usage is truncated at 1,200 characters when necessary and includes a --full hint; --full disables truncation. A missing name points to the corresponding plural command. An unknown name suggests a catalog search based on its first four lowercased characters. Successful output points to the layout rules.

Component

Syntax: pnpm gesso component <Name> [--full]

Component details include the @acromedia/gesso import.

pnpm gesso component Button
pnpm gesso component button --full

Pattern

Syntax: pnpm gesso pattern <Name> [--full]

Pattern details include the Storybook path and either a verified @acromedia/gesso root import or import: unavailable. Do not infer a root import when the command reports it as unavailable.

pnpm gesso pattern AddToCart
pnpm gesso pattern "Commerce/Add to Cart/Add to Cart Option" --full

Layout

Syntax: pnpm gesso layout <Name> [--full]

Layout details include the Storybook path and either a verified @acromedia/gesso root import or import: unavailable. Do not infer a root import when the command reports it as unavailable.

pnpm gesso layout AccountSignInForm
pnpm gesso layout "Account/Forms/Account Sign In Form" --full