What Are the Four Main Subcommands of the DESIGN.md CLI?

The DESIGN.md CLI provides four primary subcommands—spec, lint, export, and diff—that enable developers to display specifications, validate file structure, generate design artifacts, and compare document versions.

The google-labs-code/design.md repository delivers a structured command-line interface for managing design system specifications. The DESIGN.md CLI organizes its core functionality into four distinct subcommands that handle the complete document lifecycle, from inspection to transformation. Each command is implemented as a dedicated TypeScript module within the packages/cli/src/commands/ directory.

The Four Main Subcommands of the DESIGN.md CLI

spec

The spec subcommand prints the DESIGN.md specification to stdout, with optional support for displaying active linting rules. Implemented in packages/cli/src/commands/spec.ts, this utility outputs content in either Markdown or JSON format via the --format flag. Developers use this command to inspect the current schema or export specifications for integration with external tooling.

lint

The lint subcommand validates DESIGN.md files for structural correctness and compliance with defined rules. Located in packages/cli/src/commands/lint.ts, it accepts file paths or stdin input and delivers findings in JSON or plain-text formats. This makes it ideal for automated CI/CD pipelines and pre-commit hooks that enforce design document standards.

export

The export subcommand generates concrete artifacts—such as design tokens, CSS variables, or framework-specific configurations—from a DESIGN.md source file. Defined in packages/cli/src/commands/export.ts, it supports multiple output formats including Tailwind CSS. This bridges the gap between design specifications and implementation code.

diff

The diff subcommand compares two DESIGN.md specifications or analyzes differences between a specification and its generated artifacts. Found in packages/cli/src/commands/diff.ts, this functionality enables version tracking, regression testing, and validation that exported assets remain synchronized with their source specifications.

Practical Usage Examples

Display the specification in Markdown or JSON:

design-md spec            # Markdown output (default)

design-md spec --format json   # JSON output

design-md spec --rules          # Append active linting rules

Validate a DESIGN.md file:

design-md lint path/to/DESIGN.md
design-md lint - --format text   # Read from stdin, plain-text output

Export design tokens for Tailwind CSS:

design-md export path/to/DESIGN.md --format tailwind

Compare two specification versions:

design-md diff path/to/old/DESIGN.md path/to/new/DESIGN.md

Summary

• The DESIGN.md CLI centers around four subcommands that manage the complete document workflow.
• spec (packages/cli/src/commands/spec.ts) handles specification inspection and output formatting.
• lint (packages/cli/src/commands/lint.ts) provides structural validation with multiple report formats.
• export (packages/cli/src/commands/export.ts) transforms specifications into usable code artifacts.
• diff (packages/cli/src/commands/diff.ts) enables version comparison and regression detection.

Frequently Asked Questions

What does the spec subcommand do?

The spec subcommand displays the DESIGN.md specification, optionally including active linting rules. It supports both Markdown and JSON output formats via the --format flag, making it useful for documentation generation and tool integration.

How does the lint subcommand validate files?

The lint subcommand checks DESIGN.md files for structural correctness against the defined schema. It accepts file paths or stdin input and can output findings as JSON or plain text, enabling integration with automated testing pipelines and development workflows.

Can I export to multiple formats?

Yes, the export subcommand supports multiple output formats including design tokens, CSS, and framework-specific configurations like Tailwind CSS. The --format flag allows you to specify the target format when generating artifacts from your DESIGN.md source.

What is the diff subcommand used for?

The diff subcommand compares two DESIGN.md specifications or evaluates differences between a specification and its generated artifacts. This supports version tracking, change detection between iterations, and verification that exported assets match their source definitions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}