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.

# 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.

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.

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

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.

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:

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

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

Quick reference

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