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

Pass - as the file argument to read from standard input, enabling you to pipe content directly into the lint or export commands.

The DESIGN.md CLI from the google-labs-code/design.md repository supports Unix-style piping by treating - as a special filename that triggers STDIN reading. This allows you to integrate the linter and exporter into shell workflows without writing intermediate files.

The Dash Convention for Standard Input

When you pass - as the positional file argument to the DESIGN.md CLI, it instructs the tool to read from standard input (STDIN) instead of a disk file. This convention works identically across both the lint and export subcommands, making it trivial to chain the CLI with other Unix tools.

How STDIN Reading Works Under the Hood

The STDIN handling is centralized in a utility function used by the command implementations.

The readInput() Implementation

In packages/cli/src/utils.ts (lines 18-30), the readInput() function checks if the supplied path equals -. When this condition is met, the function asynchronously collects all chunks arriving on process.stdin, concatenates them, and returns the resulting string. If the path is a regular file, it reads from disk instead.

Command Integration

Two primary commands leverage this helper:

• Lint command – Located in packages/cli/src/commands/lint.ts (lines 24-38), this command calls readInput(args.file) and runs the linter on the returned text.
• Export command – Found in packages/cli/src/commands/export.ts (lines 28-34), this command uses the same pattern to read DESIGN.md content before passing it to the appropriate emitter.

Because both commands rely on the same readInput() abstraction, they process piped input identically to file-based input.

Pipe Examples for Common Workflows

You can integrate the CLI into shell pipelines using the - argument.

Lint a file from disk using standard file input:

design-md lint path/to/DESIGN.md

Pipe content from cat to lint via STDIN:

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

Use a here-document for inline input:

design-md lint - <<EOF

# DESIGN.md

## Token example

color-primary: #ff0000
EOF

Export tokens to Tailwind JSON by piping from STDIN:

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

In each case, the - argument triggers readInput() in STDIN mode, processing the streamed text exactly as if it were read from a regular file.

Summary

• Pass - as the file argument to enable STDIN mode in the DESIGN.md CLI.
• The readInput() function in packages/cli/src/utils.ts implements the STDIN logic by consuming process.stdin when the dash argument is detected.
• Both the lint and export commands support piping, allowing seamless integration with tools like cat, git show, or curl.
• Piped input is processed identically to file input, maintaining full compatibility with the DESIGN.md specification.

Frequently Asked Questions

Can I pipe DESIGN.md content from a remote URL?

Yes. You can fetch content with curl and pipe it directly into the CLI. For example: curl -s https://example.com/DESIGN.md | design-md lint -. The - argument tells the CLI to read the HTTP response body from STDIN rather than a local file.

Does the export command support all formats when using STDIN?

Yes. The export command in packages/cli/src/commands/export.ts processes STDIN input the same way it handles files, so all output formats—including json-tailwind—work with piped input without any configuration changes.

Is there a size limit for piped input?

The readInput() function asynchronously collects all chunks from process.stdin, so it handles any size stream that your system memory can accommodate, following standard Node.js stream processing patterns.

Can I use stdin with other commands besides lint and export?

Currently, the lint and export commands in the DESIGN.md CLI are the primary commands utilizing readInput(). Check the specific command implementation in packages/cli/src/commands/ to verify STDIN support for other subcommands, as they must explicitly call the helper to enable dash-argument handling.

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