# Why the designmd Alias Exists and When to Use It on Windows > Understand the designmd alias and its purpose on Windows. Avoid confusion with Markdown files and execute the designmd CLI tool effectively. - Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md) - Tags: how-to-guide - Published: 2026-06-27 --- **The `designmd` alias provides a Windows-compatible, dot-free alternative to the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI binary, preventing the OS from confusing the command with a Markdown file association and opening a document instead of executing the tool.** The `designmd` command solves a platform-specific execution conflict in the `@google/design.md` package. When developers install this CLI on Windows, the binary name [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) collides with the operating system's file extension handling. The alias ensures consistent cross-platform functionality without requiring users to rename their design documents or modify system associations. ## The Windows File Association Conflict On Windows, the `.md` extension is registered to Markdown editors and viewers. When you invoke [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) in the terminal, Windows may interpret the command as a request to open a file named [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) rather than executing the npm-installed binary. This occurs because Windows uses file extensions to determine executable handlers, and the period in [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) triggers the shell to search for a matching document before checking the `PATH` for CLI tools. ## How the designmd Alias Works The `designmd` alias points to the identical entry point as the original command. In [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json), the package's `bin` map declares both names, mapping each to [`./dist/index.js`](https://github.com/google-labs-code/design.md/blob/main/./dist/index.js). This means both commands execute the same JavaScript code, but the dot-free variant bypasses Windows shell interpretation that causes the file association conflict. ## When to Use designmd vs design.md ### On Windows Systems Always use the `designmd` alias when working on Windows. This ensures the CLI runs instead of opening a Markdown file: ```bash # Preferred method on Windows npx -p @google/design.md designmd lint DESIGN.md ``` ### On macOS and Linux On Unix-based systems, the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) command works without issues because these platforms do not rely on file extensions for executable resolution. You can use the original syntax: ```bash # Works on macOS and Linux npx @google/design.md lint DESIGN.md ``` ### In Cross-Platform npm Scripts For npm scripts that must run on any operating system, use the `designmd` alias to ensure portability. The [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) explicitly recommends this approach for teams with mixed development environments: ```jsonc { "scripts": { "design:lint": "designmd lint DESIGN.md", "design:check": "designmd validate" } } ``` ## Implementation Details The dual-binary configuration is defined in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json). The package declares both the standard name and the Windows-friendly alias in the `bin` field, ensuring npm installs both executables in your `node_modules/.bin` directory. This implementation allows the same package to support all platforms without requiring platform-specific installation logic or conditional entry points. ## Summary - **The `designmd` alias exists** to circumvent Windows file association conflicts where `.md` extensions trigger Markdown applications instead of CLI execution. - **Use `designmd` on Windows** whenever invoking the `@google/design.md` CLI to prevent the shell from opening files rather than running commands. - **Reference [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json)** to see how both binaries map to [`./dist/index.js`](https://github.com/google-labs-code/design.md/blob/main/./dist/index.js), confirming they are identical in functionality. - **Prefer `designmd` in npm scripts** for cross-platform compatibility across Windows, macOS, and Linux development environments. ## Frequently Asked Questions ### What is the designmd alias? The `designmd` alias is a dot-free alternative to the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI command installed by the `@google/design.md` package. It references the same [`./dist/index.js`](https://github.com/google-labs-code/design.md/blob/main/./dist/index.js) entry point defined in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json) but avoids Windows file extension conflicts. ### Why does design.md not work on Windows? Windows associates the `.md` extension with Markdown file viewers. When you type [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md), the OS may attempt to open a file named [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) instead of executing the CLI binary, as documented in the project's [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md). ### Can I use designmd on macOS or Linux? Yes, the `designmd` alias works on all platforms including macOS and Linux. While unnecessary on Unix systems where [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) functions normally, using `designmd` ensures your commands and scripts remain portable across all operating systems. ### How do I configure designmd in package.json scripts? Define your scripts using the alias to ensure Windows compatibility: ```json { "scripts": { "lint:design": "designmd lint DESIGN.md" } } ``` This configuration guarantees consistent behavior regardless of which operating system executes the npm script.