# The Four Hallmark Commands: Complete CLI Verb Reference

> Explore the four Hallmark CLI commands: build, audit, redesign, and study. Master these essential verbs for efficient project management with the Nutlope/hallmark repository.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: api-reference
- Published: 2026-08-09

---

**The four Hallmark commands are the default build (invoked without a verb), `audit`, `redesign`, and `study`.**

Hallmark is a design-system CLI tool that structures its entire workflow around four primary verbs. According to the source code in the Nutlope/hallmark repository, these commands—defined in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and verb-specific reference files—constitute the complete public API for generating pages, analyzing anti-patterns, and extracting design DNA.

## The Four Hallmark Verbs Explained

Hallmark operates around one default behavior and three explicit verbs, each serving distinct functions in the design workflow.

### 1. Default Build (Implicit Verb)

The default command runs the standard build pipeline when no verb is specified. As documented in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), this generates a page using the current design system without altering any existing files. It is invoked by running `hallmark <brief>` or explicitly with `hallmark build <brief>`.

### 2. audit

The `audit` verb performs a read-only safety check on target pages. According to [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), it analyzes the target against anti-pattern lists, scores the results, and returns a ranked punch-list for the user. This command never writes files, making it safe for inspection workflows.

### 3. redesign

The `redesign` verb restructures the visual and interaction layers of a page or entire application. As specified in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md), it preserves copy, routes, and component ownership while applying new macro-structures or themes. Unlike `audit`, this verb may create or update [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), token files, or other configuration assets.

### 4. study

The `study` verb extracts design "DNA"—including macrostructure, archetypes, type-pairing, and colour anchors—from screenshots or live URLs. According to [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), it produces a diagnosis report and optionally emits a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file or hands results off to the default build for immediate implementation.

## How to Use Hallmark Commands

All commands are run from the project root where the `.hallmark/` directory lives. Below are practical examples for each verb:

```bash

# 1. Default build (no verb)

hallmark build "a landing page for a small-batch honey farm"

# 2. Audit a page (read-only safety check)

hallmark audit src/pages/about.html

# 3. Redesign a page or whole app

hallmark redesign src/pages/home.tsx --mood luxury

# 4. Study a reference (screenshot or URL) and optionally lock the DNA

hallmark study ./reference.png          # image mode

hallmark study https://example.com      # URL mode

```

The `audit` verb operates in read-only mode, while `redesign` and `study` may modify project files as part of their workflow.

## Source Files Defining the Verb API

The implementation and specifications for these commands are maintained in the following files:

- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) — Central specification listing the default behavior and three explicit verbs
- [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) — Implementation notes for the `audit` verb, including scoring rules and output format
- [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) — Specification for the `redesign` verb, covering multi-page flows and mood handling
- [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) — Protocol for the `study` verb, describing source-mode detection and DNA extraction

## Summary

- Hallmark provides **four primary commands**: the default build, `audit`, `redesign`, and `study`.
- The **default build** generates pages without altering files and runs when no verb is specified.
- The **audit** verb performs read-only safety checks against anti-patterns.
- The **redesign** verb restructures visual layers while preserving content and routes.
- The **study** verb extracts design DNA from references and produces diagnostic reports.

## Frequently Asked Questions

### What is the difference between audit and study in Hallmark?

The `audit` verb evaluates existing pages against anti-pattern lists to identify issues, while the `study` verb analyzes external references (screenshots or URLs) to extract design DNA and archetypes. `audit` is read-only and never writes files, whereas `study` may generate [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) or other output files.

### Does the default Hallmark command modify existing files?

No. According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the default build behavior generates pages using the current design system without altering any existing files in the project. It operates as a pure generation command that respects the existing project state.

### Can I run Hallmark without specifying a verb?

Yes. Running `hallmark <brief>` invokes the default build behavior. You can also use the explicit form `hallmark build <brief>` for the same result. This implicit verb triggers the build pipeline immediately without requiring explicit command typing.

### What files does the redesign verb update?

The `redesign` verb may create or update [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json), [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), or token files as part of its flow, according to the specification in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md). These updates track the transformation history and design token changes applied during the restructuring process.