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

> Explore the four main subcommands of the DESIGN.md CLI: spec, lint, export, and diff. Learn how to display specifications, validate structure, generate artifacts, and compare versions.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
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:

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

```

Export design tokens for Tailwind CSS:

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

```

Compare two specification versions:

```bash
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`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/spec.ts)) handles specification inspection and output formatting.
- **`lint`** ([`packages/cli/src/commands/lint.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/lint.ts)) provides structural validation with multiple report formats.
- **`export`** ([`packages/cli/src/commands/export.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/export.ts)) transforms specifications into usable code artifacts.
- **`diff`** ([`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/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.