# Designmdme CLI

> Generate a DESIGN.md design-system spec (color tokens, typography, spacing, shadows, components) and optional HTML preview from any website URL using the designmdme CLI. Use when the user wants to extract, capture, replicate, or reference a website's design system or visual style — e.g. "build a UI like stripe.com", "match this brand's look", "get the design tokens for linear.app", "make my app look like notion.so", or any time you need an accurate color palette, font stack, or component styling from a real site before writing UI code.

- Skill: `crowdlinker/designmdme-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add crowdlinker/designmdme-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/crowdlinker/designmdme-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- License: Proprietary
- Author: crowdlinker (https://skillmd.com/u/crowdlinker)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/crowdlinker/designmdme-cli

---


# designmdme CLI

`designmdme` turns any public website into a **DESIGN.md** — a structured Markdown
spec of that site's design system (color tokens, typography scale, spacing, border
radius, shadows/elevation, and component patterns). It can optionally also produce a
self-contained **HTML preview** that renders those tokens as live visual specimens.

The DESIGN.md is built to be fed to coding agents: when a user asks you to build or
restyle a UI to match a real brand, generate the spec first, read it, then write code
against its exact token values instead of guessing colors and fonts.

## When to use this skill

Use it whenever the task depends on an accurate, real design system from a live site:

- "Build a landing page in the style of stripe.com" → generate `stripe.com`, read the
  DESIGN.md, then implement using its actual hex values and font stack.
- "Match our marketing site's design" / "make this look on-brand" → extract that URL.
- "What's linear.app's color palette / font?" → generate and read the relevant section.
- Setting up a new project's design tokens from an existing reference site.

If the user only wants a quick visual impression and no code, the HTML preview
(`--html`) is the shareable artifact. For everything code-related, the Markdown is the
source of truth.

## Install

The binary is `designmdme`, published as `@crowdlinker/designmdme`.

```bash
# One-off (no install)
npx @crowdlinker/designmdme stripe.com

# Or install globally so the `designmdme` command is always available
npm install -g @crowdlinker/designmdme
```

## Authentication (one-time, interactive)

The CLI is account-gated; generation requires a logged-in token. Auth uses a browser
device-code flow and stores a token at `~/.designmdme/auth.json` (token + expiry only,
no other PII). Tokens default to a 30-day lifetime.

```bash
designmdme login     # opens a browser, prints a fallback URL + code, then polls
designmdme whoami    # prints the logged-in email + token expiry
designmdme logout    # deletes ~/.designmdme/auth.json
```

`login` is **interactive** (it opens a browser and waits up to 10 minutes for the user
to approve). Do not run it unattended. If a command fails with "Not logged in" or
"Token expired", stop and ask the user to run `designmdme login` themselves — you
cannot complete the browser approval for them.

## Generate a DESIGN.md (the default command)

The URL may be passed as a positional argument or via `-w`/`--website`; both are
equivalent. `http`/`https` and `www.` are normalized automatically.

```bash
designmdme stripe.com
designmdme --website https://stripe.com
```

What happens: the CLI checks the token, verifies the URL is reachable, scans the site,
streams the spec, and writes the file. Default output name is `DESIGN-<slug>.md` in the
current directory, where `<slug>` is the hostname with `www.` stripped and non-alphanumeric
characters collapsed to hyphens (e.g. `stripe.com` → `DESIGN-stripe-com.md`).

### Options

| Flag | Meaning |
|------|---------|
| `-w, --website <url>` | Website URL — alias for the positional argument. |
| `-o, --output <path>` | Write to a specific path instead of `DESIGN-<slug>.md`. Parent dirs are created if missing. |
| `--single-page` | Extract only the landing page (**4 credits**). See [Extraction modes](#extraction-modes). |
| `--multi-page` | Crawl the site's key pages for a richer spec (**8 credits**). |
| `--html` | Also generate an HTML preview alongside the Markdown (**+8 credits** — see [Credit costs](#credit-costs)). Written to the same path with `.html` instead of `.md`. |

```bash
designmdme stripe.com --output ./docs/stripe-design.md
designmdme stripe.com --single-page           # cheapest, predictable 4 credits
designmdme --website stripe.com --html        # writes DESIGN-stripe-com.md + .html
```

## Extraction modes

The spec can be built from just the landing page or from several of the site's key
pages crawled and merged:

- **Single-page** (`--single-page`, **4 credits**) — reads only the URL you pass.
- **Multi-page** (`--multi-page`, **8 credits**) — discovers and reads key pages
  (pricing, product, features, …) for a more complete design system.

If you pass **neither** flag, the CLI uses the **account's saved preference** (which may
be multi-page, i.e. 8 credits) and prints the resolved mode + cost before generating.
**For predictable cost, pass the mode explicitly** — use `--single-page` when you just
need the tokens cheaply, `--multi-page` when completeness matters.

Two things the CLI handles automatically:
- If the account balance is below 8 credits, multi-page falls back to single-page.
- If a site turns out to be a **single route** (nothing extra to crawl), it's billed as
  single-page (4) even with `--multi-page`, and prints a note saying so.

### Important: avoid the interactive overwrite prompt

If the target file already exists, the CLI **interactively prompts** "Replace or create
a copy? (replace/copy)" and blocks waiting for input. When running non-interactively
(which is the normal case for an agent), this will hang. To stay safe:

- Pass an explicit, unique `--output` path that doesn't already exist, **or**
- Check for / remove the default `DESIGN-<slug>.md` first.

If the prompt is answered "copy" (the default), the copy is named
`DESIGN-<slug>-YYYYMMDD.md` (date-stamped).

## Generate an HTML design preview

Add `--html` to also produce a self-contained HTML page that renders the extracted
design system as **live visual specimens**: color swatches with hex labels, type-scale
specimens set in the site's actual fonts, spacing and radius bars, shadow/elevation
cards, and a copy-ready `:root` CSS-variables block. It is a single standalone `.html`
file with all CSS inlined and no external dependencies — useful for sharing with
designers, dropping into a wiki, or eyeballing the brand before building.

```bash
designmdme stripe.com --html     # writes DESIGN-stripe-com.md AND DESIGN-stripe-com.html
```

Behavior:

- The HTML is written **alongside the Markdown** — same path, `.html` instead of `.md`
  (control the base path with `--output`). It is subject to the same overwrite prompt.
- HTML is generated **from the Markdown spec**, so the Markdown is always produced
  first. If the HTML step fails (e.g. not enough credits), the `.md` file is still saved.
- For code tasks, prefer the **Markdown** — it is the machine-readable source of truth.
  Reach for `--html` only when the user wants a visual artifact to view or share.

## Credit costs

Generation consumes account credits. Exact costs:

| What you generate | Credits |
|-------------------|---------|
| `DESIGN.md` — single-page (`--single-page`) | **4** |
| `DESIGN.md` — multi-page (`--multi-page`) | **8** |
| HTML preview — the `--html` add-on | **8** |
| Single-page **+** HTML | **12** total (4 + 8) |
| Multi-page **+** HTML | **16** total (8 + 8) |

Notes:

- Credits are charged **only on success** — a failed or cancelled generation never costs
  anything.
- A cached result costs **0**: re-generating a site that was already generated serves the
  cached Markdown (the CLI prints "Served from cache · 0 credits").
- The HTML preview is likewise billed once and cached — re-running `--html` for the same
  site serves the cached file and does **not** charge again.
- If `--html` reports **"Insufficient credits"**, the Markdown has already been saved
  successfully — only the HTML add-on was skipped. Do not retry in a loop; tell the user
  to top up at https://designmd.me/pricing.
- Multi-page needs 8 credits; if the balance is lower the CLI silently uses single-page.
  Check `designmdme usage` first when cost matters.

## Inspect history and usage

```bash
designmdme list      # recent generations (CLI + web), with share URLs and local file paths
designmdme usage     # credit balance, credits used vs received, generation counts, recent transactions
```

`list` annotates each row with a **`[multi-page]`** tag (when applicable) and a **status**
(`● queued` / `● processing` / `● failed` / `● cancelled`; successful rows just show their
share link/file). Because generations run as durable background jobs, `list` is how you
check on one that's still processing or resume after an interruption.

Check `designmdme usage` before a batch of generations to confirm there are enough
credits (4 single / 8 multi per Markdown, 8 more per `--html`). If the balance is empty,
stop and tell the user to top up at https://designmd.me/pricing — do not retry in a loop.

## Background generation

Generations are durable server-side jobs. A normal `designmdme <url>` call still **blocks
until the file is written** — it shows live status (`Queued → Generating`) and returns
when done, so the agent workflow is unchanged (it may just take a little longer under
load). If interrupted (Ctrl+C / dropped connection), the job **keeps running** on the
server rather than cancelling — run `designmdme list` afterwards to see its status and,
once complete, the result.

## Recommended agent workflow

1. Confirm auth only if needed: a generate call will fail fast with a clear message if
   not logged in. Don't preemptively run `login` (it's interactive).
2. Generate to a known path with an explicit mode for predictable cost:
   `designmdme <url> --single-page --output <unique-path>.md` (or `--multi-page` when a
   more complete, cross-page spec is worth 8 credits).
3. **Read the generated DESIGN.md** and pull exact values — hex codes, font families
   and sizes, spacing units, radii, shadow values, component styles. Use those verbatim
   in the code you write; do not approximate.
4. If the user wants a visual reference too, add `--html` and open the `.html` file.

## Troubleshooting

| Symptom | Cause / action |
|---------|----------------|
| `Not logged in` / `Token expired` / `Token is no longer valid` | Ask the user to run `designmdme login`. Auth is interactive; you can't do it for them. |
| Hangs after "already exists" | Interactive overwrite prompt — re-run with a unique `--output` path. |
| `Insufficient credits for HTML preview` | Out of credits for `--html`; the Markdown may still have succeeded. Tell the user to top up at https://designmd.me/pricing. |
| Unexpected 8-credit charge | No mode flag was passed and the account default is multi-page. Pass `--single-page` for a predictable 4-credit run. |
| URL reachability failure | The site is down, blocking bots, or the URL is wrong. Confirm the URL with the user. |
| Empty output | Generation returned nothing — retry once; if it persists, report it. |

## Quick reference

```bash
designmdme login                              # one-time browser auth
designmdme whoami                             # who am I + token expiry
designmdme stripe.com --single-page           # → DESIGN-stripe-com.md (4 credits)
designmdme stripe.com --multi-page            # richer, cross-page spec (8 credits)
designmdme stripe.com                         # uses account default mode (prints cost first)
designmdme stripe.com --output ./docs/s.md    # custom path (avoids overwrite prompt)
designmdme stripe.com --single-page --html    # also write .html preview (+8 credits)
designmdme list                               # recent generations (with mode + status)
designmdme usage                              # credits + generation stats
designmdme logout                             # remove stored credentials
```