# Troubleshooting DESIGN.md CLI Installation on Windows: Complete Guide

> Troubleshoot DESIGN.md CLI installation on Windows. Learn why the .md extension causes issues and discover solutions to run the command successfully. Get your CLI working now.

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

---

**On Windows, the [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) command fails because the operating system interprets the `.md` extension as a Markdown file association rather than an executable, forcing you to use the `designmd` alias or quoted package names to run the CLI successfully.**

Installing the `@google/design.md` package on Windows often results in silent failures or the accidental launching of Markdown editors instead of command execution. This issue stems from a fundamental conflict between the CLI's default executable name and Windows file association handling. This guide explains the root cause documented in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository and provides verified workarounds to resolve installation and execution errors on Windows systems.

## Why DESIGN.md CLI Fails on Windows

The `@google/design.md` CLI declares two binaries in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json) at lines 22–25: [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) pointing to [`./dist/index.js`](https://github.com/google-labs-code/design.md/blob/main/./dist/index.js), and `designmd` as an alias pointing to the same entry point. On Windows, the command shell resolves [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) by searching for `design.md.exe` or falling back to the file association for `.md` files. Because Windows treats `.md` as a document extension rather than an executable suffix, invoking the command opens the file in the default Markdown editor instead of executing the Node.js script, resulting in no CLI output or unexpected application launches.

## How to Fix DESIGN.md CLI Installation Errors on Windows

### Quote the Package Name During Installation

PowerShell interprets the `@` symbol as a special character, which can cause syntax errors when running installation commands. Always quote the package name to ensure proper resolution.

```bash
npm install "@google/design.md"

```

### Use the designmd Alias to Bypass File Associations

The `designmd` alias avoids the `.md` extension collision entirely. When using `npx`, prepend the package with `-p` and invoke the alias directly to ensure cross-shell compatibility on Windows.

```bash
npx -p @google/design.md designmd lint path/to/DESIGN.md

```

This command explicitly calls the alias defined in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json), bypassing Windows file association logic.

### Add an npm Script for Cross-Platform Compatibility

For project-level consistency, add a script to your [`package.json`](https://github.com/google-labs-code/design.md/blob/main/package.json) that uses the `designmd` alias. This abstraction ensures the command works regardless of the host operating system.

```json
{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

```

Running `npm run design:lint` now resolves the correct binary through the local Node_modules `.bin` directory, avoiding Windows shell resolution issues.

### Verify npm Registry Configuration

An `ENOVERSIONS` error during installation typically indicates a misconfigured npm registry rather than a package-specific problem. Verify your registry points to the official npm source.

```bash
npm config get registry

# Expected output: https://registry.npmjs.org/

```

If the output differs, reset the registry and clear the cache before retrying installation.

## Quick Checklist for Windows Installation

- **Quote the install command**: Run `npm install "@google/design.md"` (or `pnpm add "@google/design.md"`).
- **Prefer the alias**: Use `npx -p @google/design.md designmd lint DESIGN.md` instead of [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md).
- **Abstract with scripts**: Add `"design:lint": "designmd lint DESIGN.md"` to [`package.json`](https://github.com/google-labs-code/design.md/blob/main/package.json).
- **Verify registry**: Confirm `npm config get registry` returns `https://registry.npmjs.org/`.
- **Avoid direct invocation**: Never call the bare [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) binary from the command line on Windows.

## Summary

- The [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) executable conflicts with Windows file associations for `.md` documents.
- Use the `designmd` alias defined in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json) to execute commands successfully.
- Quote package names in PowerShell to prevent syntax errors with the `@` scope.
- Configure npm scripts to provide a consistent interface across operating systems.
- Check npm registry settings when encountering `ENOVERSIONS` errors during installation.

## Frequently Asked Questions

### Why does running [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) open my Markdown editor instead of the CLI?

Windows treats any string ending in `.md` as a document file, triggering the default file association for Markdown editors. When you type [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md), the shell looks for an executable named `design.md.exe`, fails to find it, and falls back to opening the file association. This behavior occurs in PowerShell, Command Prompt, and Git Bash alike.

### What is the difference between [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) and `designmd` commands?

Both commands map to the same entry point at [`./dist/index.js`](https://github.com/google-labs-code/design.md/blob/main/./dist/index.js) as declared in [`packages/cli/package.json`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/package.json). The [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) name follows npm naming conventions for the package, while `designmd` serves as a Windows-compatible alias that avoids the file extension conflict. Functionally, they execute identical code from [`packages/cli/src/commands/lint.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/lint.ts).

### How do I fix `ENOVERSIONS` errors when installing the package?

An `ENOVERSIONS` error typically indicates your npm client is querying a registry that does not host the package, such as a private corporate registry or an outdated mirror. Run `npm config get registry` to verify it points to `https://registry.npmjs.org/`. If necessary, reset with `npm config set registry https://registry.npmjs.org/` and clear the cache with `npm cache clean --force`.

### Can I use the DESIGN.md CLI in Git Bash on Windows?

Yes, but the `.md` extension issue persists across all Windows shells including Git Bash, because the underlying Windows API still handles file associations. You must use the `designmd` alias or invoke the CLI through npm scripts to ensure proper execution. Direct calls to [`design.md`](https://github.com/google-labs-code/design.md/blob/main/design.md) will still trigger the file association behavior even in Unix-like emulators.