How to Use stdin with the DESIGN.md CLI for Piping Input

The DESIGN.md CLI accepts - as a special filename that tells the tool to read from standard input (STDIN), enabling you to pipe content directly from other commands like cat, git show, or curl.

The google-labs-code/design.md repository provides a command-line interface for parsing and exporting design tokens from DESIGN.md files. While the CLI typically reads from a file path supplied as a positional argument, it also supports reading from standard input when you pass - as the filename. This allows you to integrate the tool into shell pipelines and process generated content without writing intermediate files to disk.

How STDIN Handling Works in the DESIGN.md CLI

The STDIN functionality is implemented in the readInput() helper function located in packages/cli/src/utils.ts (lines 18-30). When you pass - as the file argument, the function asynchronously collects all chunks from process.stdin, concatenates them into a string, and returns the content for processing exactly as if it had been read from a regular file.

The readInput() Utility Function

In packages/cli/src/utils.ts, the readInput() function checks if the supplied path equals the string -. When this condition is met, the function enters STDIN mode and streams data from process.stdin instead of attempting to open a file on disk. This implementation ensures that both piped data and here-documents are captured correctly before being passed to the command logic.

Commands That Support STDIN

Both the lint and export commands utilize the readInput() utility to support STDIN input. In packages/cli/src/commands/lint.ts (lines 24-38), the command calls readInput(args.file) and runs the linter on the resulting text. Similarly, packages/cli/src/commands/export.ts (lines 28-34) reads the DESIGN.md content via readInput() before passing it to the appropriate emitter for format conversion.

Practical Examples of Piping to the DESIGN.md CLI

You can pipe content into any DESIGN.md CLI command that accepts a file argument by using - as the filename. This works with shell redirections, pipes from other commands, and here-documents.

Lint a file from disk as a baseline:

design-md lint path/to/DESIGN.md

Pipe content from cat into the linter:

cat path/to/DESIGN.md | design-md lint -

Use a here-document to provide inline content:

design-md lint - <<EOF

# DESIGN.md

## Token example

color-primary: #ff0000
EOF

Export tokens from STDIN to Tailwind JSON format:

cat path/to/DESIGN.md | design-md export - json-tailwind

In each example, the - argument tells the CLI to invoke readInput() in STDIN mode, so the streamed text is processed identically to file-based input.

Summary

• The DESIGN.md CLI treats - as a special filename that triggers STDIN reading via the readInput() function in packages/cli/src/utils.ts.
• Both the lint and export commands support piped input, allowing seamless integration with other command-line tools.
• You can use shell pipes, here-documents, or process substitution to stream DESIGN.md content without creating temporary files.

Frequently Asked Questions

Can I pipe content to any DESIGN.md CLI command?

Yes, any command that accepts a file path argument supports the - convention for STDIN input. According to the source code in google-labs-code/design.md, both the lint and export commands use the readInput() utility in packages/cli/src/utils.ts, making them compatible with piped data from other processes.

How does the CLI differentiate between a file named - and STDIN?

The readInput() function specifically checks if the argument equals the string -. If you have an actual file named -, you would need to reference it using a relative path like ./- or the absolute path to avoid triggering STDIN mode, as the literal - is reserved for standard input.

Does using STDIN affect how the linter processes DESIGN.md files?

No, the content is processed identically whether it comes from a file or STDIN. In packages/cli/src/commands/lint.ts, the readInput() function returns a string that is passed directly to the linter, so validation rules, token parsing, and error reporting work the same way for both input methods.

Can I use here-documents with the DESIGN.md export command?

Yes, here-documents work with any command that supports STDIN input. You can write design-md export - json-tailwind <<EOF followed by your DESIGN.md content and the closing EOF to export tokens directly from the shell without creating a physical file on disk.

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