dmdg — Design MD Generator CLI

Generate AI-ready DESIGN.md documentation from local design files or GitHub repositories.

Installation

npm install -g dmdg-cli

Or use with npx (no install required):

npx dmdg-cli <command>

Getting Started

1. Get your API token

1. Go to https://design-md-generator.pages.dev/account
2. Sign in with GitHub
3. Create a new API token (give it a name like "MacBook Pro" or "Work Desktop")
4. Copy the token immediately — you won't see it again

2. Authenticate

dmdg login <your-api-token>

Your token is saved locally in ~/.config/design-md/config.json with 0600 permissions.

3. Verify login

dmdg whoami

4. Generate DESIGN.md

From local files

dmdg generate ./src

The CLI recursively scans the target directory for supported source files, reads their contents, and sends them to the API for server-side extraction and AI-powered enhancement.

dmdg generate ./styles.css -o docs/DESIGN.md

From a GitHub repository

dmdg generate owner/repo --repo

The server analyzes the repository directly (including private repos if you have connected your GitHub account on the web app).

Commands

| Command | Description | |---------|-------------| | dmdg login <token> | Save your API token locally | | dmdg logout | Remove the saved API token | | dmdg whoami | Show the authenticated GitHub user | | dmdg generate <path> | Generate DESIGN.md from local files (requires token) | | dmdg generate <repo> --repo | Generate DESIGN.md from a GitHub repo (requires token) | | dmdg init [dir] | Scaffold a .designmdrc config file | | dmdg init [dir] --template | Also create a starter DESIGN.md template |

Options

dmdg generate <path> --repo       # Treat path as owner/repo
dmdg generate <path> -o <file>    # Output file (default: DESIGN.md)
dmdg generate <path> --output <file>

Project Config (.designmdrc)

Create a .designmdrc in your project root to customize file discovery:

{
  "include": ["src/**/*.{css,scss,html}"],
  "exclude": ["node_modules", "dist", "build"],
  "output": "DESIGN.md",
  "title": "My Design System"
}

The CLI automatically discovers .designmdrc when running generate.

Environment Variables

| Variable | Description | |----------|-------------| | DESIGN_MD_API_BASE | API base URL (default: https://design-md-generator.pages.dev) | | DESIGN_MD_TOKEN | API token (alternative to dmdg login) |

Examples

# Authenticate
dmdg login dmd_abc123...

# Generate from a local project directory
dmdg generate ./my-project

# Generate from a single CSS file
dmdg generate ./styles.css

# Generate with custom output path
dmdg generate ./src -o ./docs/DESIGN.md

# Generate from a public GitHub repo
dmdg generate facebook/react --repo

# Generate from a private GitHub repo (requires GitHub auth on the web app)
dmdg generate mycompany/private-repo --repo

# Scaffold config
dmdg init ./my-project --template

Supported File Types

The CLI scans for and sends the following file types to the API:

• Stylesheets: .css, .scss, .less, .sass
• HTML: .html, .htm
• Config files: tailwind.config.*, postcss.config.*, vite.config.*, svelte.config.*
• Package metadata: package.json

Ignored directories: node_modules, .git, dist, build, .svelte-kit, .next, out, coverage, .wrangler

Files larger than 10 MB are automatically skipped.

How It Works

1. Scan — Recursively discovers supported files in the target directory (or reads a single file)
2. Read — Reads the raw contents of discovered files locally
3. Send — Uploads file contents to the API along with your authentication token
4. Extract — The server parses colors, fonts, spacing, shadows, borders, animations, and components
5. Enhance — The server runs AI-powered enrichment to produce a polished, structured DESIGN.md
6. Receive — Writes the generated DESIGN.md to your local filesystem

All heavy lifting (parsing, normalization, deduplication, and AI enhancement) happens on the server. The CLI is a thin client that collects and uploads your source files.

License

MIT