# How to Use the Nutlope Hallmark CLI: Complete Command Guide

> Master the Nutlope hallmark CLI to generate UIs, audit code, redesign, or study design DNA from reference sites. Explore the complete command guide for Nutlope/hallmark.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-10

---

**Run `hallmark` with one of four verbs—default (build), `audit`, `redesign`, or `study`—to generate non-generic UIs, score existing code, or extract design DNA from reference sites.**

The **Hallmark CLI** is a specialized tool for AI-assisted workflows that helps you build user interfaces that avoid the "AI-generated" look. Developed by Nutlope, this skill installs via `npx` and integrates directly with coding assistants like Claude Code, Cursor, and Codex. This guide covers all four CLI verbs, installation paths, and practical workflows based on the actual source code.

## Installation and Setup

Install the Hallmark skill using the `npx skills` command:

```bash
npx skills add nutlope/hallmark

```

Re-running this command updates the skill to the latest version. The CLI binaries are placed in assistant-specific directories depending on your environment:

| Assistant | Installation Path |
|-----------|-------------------|
| Claude Code | `~/.claude/skills/hallmark/` |
| Cursor | `.cursor/rules/hallmark.mdc` (content from [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)) |
| Codex (personal) | `~/.codex/skills/hallmark/` |
| Codex (project) | `.codex/skills/hallmark/` |

After installation, the `hallmark` command becomes available in your terminal. The core logic resides in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), which defines the rule-set for all four verbs.

## The Four Hallmark CLI Commands

### Default: Build a New UI from Brief

Running `hallmark` without arguments triggers the default verb, which constructs a complete UI from a design brief in your current directory.

```bash
hallmark

```

This command executes a full pipeline: it selects a **macrostructure**, applies one of **21 built-in themes**, runs **57 slop-test gates** to catch generic patterns, and outputs self-contained HTML and CSS files. The resulting page is designed to look intentionally crafted rather than AI-generated.

### Audit: Score Code Against Anti-Patterns

The `audit` verb analyzes existing code without making automatic edits. It identifies Hallmark anti-patterns such as over-reliance on utility classes, unanchored color palettes, or generic component structures.

```bash
hallmark audit ./src

```

Output includes a punch-list of warnings categorized by severity. Common detection patterns include:

- Generic utility class overuse
- Color systems not anchored to OKLCH
- Missing typographic hierarchy
- Predictable layout grids

Use this to assess whether a codebase meets Hallmark's design quality standards before refactoring.

### Redesign: Preserve Content, Refresh Visuals

The `redesign` verb rebuilds the visual layer while preserving information architecture, copy, and brand assets. This is useful when you want a fresh design fingerprint without rewriting content.

```bash
hallmark redesign ./src

```

Hallmark dissolves the existing visual structure, then re-synthesizes the page using its macrostructure library and theme system. The resulting files maintain all original text content but present it through an entirely new design lens.

### Study: Extract Design DNA from References

The `study` verb scrapes reference designs—either live URLs or local screenshots—and extracts their core design parameters.

```bash
hallmark study https://www.usehallmark.com/examples/tally/

```

Hallmark identifies three key elements:

1. **Macrostructure** – the high-level layout pattern
2. **Typography pairing** – the font combination and scale system
3. **Color anchor** – the base color methodology (often OKLCH-based)

Add the `--output` flag to generate a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file:

```bash
hallmark study https://example.com/page --output design.md

```

This file can be handed off to other AI tools or used as a reference for subsequent `hallmark` commands.

## Complete Workflow Examples

### New Project Bootstrap

```bash

# Create project directory with design brief

mkdir my-landing-page && cd my-landing-page
echo "SaaS pricing page for AI code review tool" > brief.txt

# Generate the UI

hallmark

# → index.html, style.css, and assets created

```

### Refactoring an Existing Codebase

```bash

# First, assess current state

hallmark audit ./legacy-site

# Review output, then apply redesign

hallmark redesign ./legacy-site

# Verify improvements with second audit

hallmark audit ./legacy-site

```

### Building a Design System from References

```bash

# Extract patterns from multiple references

hallmark study https://site1.com --output ref1.md
hallmark study https://site2.com --output ref2.md

# Use extracted DNA to inform new design

hallmark  # uses brief.md combined with learned patterns

```

## Core Architecture and Key Files

Understanding the file structure helps when customizing or debugging:

| File | Purpose |
|------|---------|
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Core rule-set defining all four CLI verbs |
| `skills/hallmark/references/` | Design references including macrostructures, color palettes, typography systems, and custom theme logic |
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Skill manifest with entry point and `serve` script for demos |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Reference implementation showing expected output format |
| [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) | Advanced usage patterns and command chaining techniques |

The CLI parses your input, consults [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) for behavior definitions, and applies rules from the `references/` directory to transform or generate code. All output is generated through this consistent rule pipeline rather than hardcoded templates.

## Summary

- **Install** with `npx skills add nutlope/hallmark`
- **Build** new UIs by running `hallmark` in a directory with a brief
- **Audit** existing code with `hallmark audit <path>` to catch anti-patterns
- **Redesign** while preserving content using `hallmark redesign <path>`
- **Study** reference designs via `hallmark study <url>` to extract portable design DNA

Each command consumes the same rule-set defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), ensuring consistent quality whether you're generating, analyzing, or transforming UI code.

## Frequently Asked Questions

### How do I update the Hallmark CLI to the latest version?

Re-run the installation command: `npx skills add nutlope/hallmark`. According to the repository README, this automatically pulls the latest skill version and updates the binaries in your assistant's skill directory without requiring manual file management.

### What file format does `hallmark study` output?

By default, the study verb prints extracted design parameters to your terminal. When you specify `--output design.md`, it generates a structured Markdown file containing macrostructure, typography pairing, and color anchor details that other AI tools can parse and apply to new designs.

### Can I customize the 21 built-in themes?

Yes. The `skills/hallmark/references/` directory contains the theme definitions and custom-theme logic. Advanced users can extend or override these references, as documented in [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md), to introduce company-specific design systems while maintaining Hallmark's anti-slop testing pipeline.

### Why does `hallmark audit` not auto-fix detected issues?

The audit verb intentionally produces reports without automatic edits. This design choice—implemented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)—ensures developers review and understand each anti-pattern before applying changes, preventing superficial fixes that might pass gates without addressing underlying design quality problems.