pantone-cli

Offline Pantone color matching for terminals, scripts, and AI agents.

pantone-cli matches HEX or Lab input against an offline Pantone index, returns the closest color per book, and can include API-exported shades and harmonies for the matched color. The default output is a readable terminal report with RGB color swatches. JSON output is available for tools and pipelines.

The npm package ships no color data. Get an index once with fetch-index (or build your own — see Bring Your Own Data); after that, matching is fully offline.

Install And Run

Run without installing:

npx pantone-cli fetch-index        # one-time index download
npx pantone-cli match "#0014DC"
bunx pantone-cli match "#0014DC"

Install globally:

npm install -g pantone-cli
pantone-cli fetch-index
pantone-cli match "#0014DC"

With Bun:

bun install -g pantone-cli
pantone-cli books

Agent Skill

An agent skill that teaches AI agents (Claude Code, Cursor, Codex, and others) how and when to use pantone-cli ships in this repo under skills/pantone-cli/. Install it into a project with:

npx skills add malhashemi/pantone-cli

The skill covers book selection by medium, JSON usage, Delta E00 interpretation, and the matching disclaimer agents should relay.

What Ships

The npm package contains code only:

| Included | Purpose | | --- | --- | | dist/cli.js | Node-compatible CLI binary. | | README.md | Human and agent documentation. | | .env.example | Maintenance/export configuration template. |

Color data is distributed separately as a versioned, sha256-verified artifact (see Index Data). After fetch-index, matching and book lookup are fully offline.

Important Disclaimer

pantone-cli uses CIEDE2000 against the offline Lab values in the local index. HEX input is converted from sRGB to D50 Lab using Bradford chromatic adaptation before matching.

Pantone Connect may use proprietary matching algorithms, substrate assumptions, product-specific transformations, and internal heuristics. This CLI is not a substitute for Pantone Connect, physical Pantone guides, or official Pantone production guidance.

Use only with Pantone data you are licensed to use. Pantone names and marks belong to their respective owners. This project is not affiliated with Pantone.

Quick Start

Install the offline index (once):

pantone-cli fetch-index

List books and their intended media:

pantone-cli books

Match a HEX color across all books:

pantone-cli match "#0014DC"

Match only specific books:

pantone-cli match "#0014DC" --books pantoneSolidCoated,pantoneSolidUncoated

Return JSON for another tool:

pantone-cli match "#0014DC" --json

Match a Lab color directly:

pantone-cli match --lab 33.31 23.24 -58.02

Disable terminal color swatches:

pantone-cli match "#0014DC" --no-color

Swatches are also disabled automatically when output is piped (stdout is not a TTY) or when NO_COLOR is set.

Commands

| Command | Audience | Description | | --- | --- | --- | | pantone-cli fetch-index | Users, agents, scripts | Download and install the offline match index (one-time). | | pantone-cli match | Users, agents, scripts | Offline color matching by HEX or Lab. | | pantone-cli books | Users, agents, scripts | Discover book IDs, intended uses, and medium assumptions. | | pantone-cli export | Maintainers, BYOD | Export licensed Pantone Connect catalogue data. | | pantone-cli index | Maintainers, BYOD | Build the offline match index from an export. | | pantone-cli publish-index | Maintainers, teams | Package (and optionally release) an index for distribution. |

Command help:

pantone-cli help
pantone-cli help match
pantone-cli help books
pantone-cli help fetch-index
pantone-cli help export
pantone-cli help index
pantone-cli help publish-index

Matching

Text output is meant for humans:

pantone-cli match "#0014DC" --books pantoneSolidUncoated --no-color

Example output:

PANTONE MATCH
=============
Input   [#0014DC]  #0014DC  rgb(0, 20, 220)
Lab     L 26.27  a 56.63  b -97.68
Method  CIEDE2000

PANTONE Solid Uncoated
----------------------
Book ID   pantoneSolidUncoated
Best for  Graphic Design
Medium    Spot Color Ink on Uncoated Paper
Match     [#3F43AD] Blue 072 U #3F43AD  Delta E00 10.79
Color     #3F43AD  rgb(63, 67, 173)  L 33.31  a 23.24  b -58.02
Location  page 154, position 1301

JSON output is meant for machines:

pantone-cli match "#0014DC" --books pantoneSolidUncoated --json

The JSON includes:

| Field | Meaning | | --- | --- | | input.hex | Normalized input HEX when HEX was provided. | | input.lab | Lab value used for matching. | | index | Index file path used by the command. | | results[].book | Book metadata, including target use and medium. | | results[].color | Closest color in that book. | | results[].deltaE | CIEDE2000 distance. Lower is closer. | | results[].relationships.shades | API-exported shade groups for the matched color. | | results[].relationships.harmonies | API-exported harmony groups for the matched color. |

Use compact JSON by skipping relationships:

pantone-cli match "#0014DC" --books pantoneSolidUncoated --json --no-relationships

Book Discovery

Book IDs are the values passed to --books.

pantone-cli books
pantone-cli books --json
pantone-cli books --search textile
pantone-cli books pantoneSolidCoated

Book output includes:

| Field | Use For Agents | | --- | --- | | id | Exact value for match --books. | | title | Human-readable book name. | | group | Pantone library family. | | info.en.target | Intended design/application use. | | info.en.description | Physical medium or reproduction assumption. | | info.en.group | Broader product context. | | colorCount | Number of colors available in the offline index. |

Common examples from the current index:

| Book ID | Best Use | Medium Assumption | | --- | --- | --- | | pantoneSolidCoated | Graphic design | Spot color ink on coated paper. | | pantoneSolidUncoated | Graphic design | Spot color ink on uncoated paper. | | pantoneColorBridgeCoated | Spot vs process evaluation | Spot color and process ink on coated paper. | | pantoneColorBridgeUncoated | Spot vs process evaluation | Spot color and process ink on uncoated paper. | | pantoneFhCottonTcx | Fashion, textiles, soft home | Dye on cotton fabric. | | pantoneFhiPaperTpg | Product design | Lacquer coating on paper. | | pantoneCmykCoated | Graphic design | CMYK process ink on coated paper. | | pantoneCmykUncoated | Graphic design | CMYK process ink on uncoated paper. |

Agent Usage Guide

For AI agents and automation, prefer JSON and explicit book filters.

Recommended flow:

1. Run pantone-cli books --json to inspect available book IDs and medium assumptions.
2. Choose book filters based on the user intent, such as coated print, uncoated print, textile, product design, or CMYK process.
3. Run pantone-cli match <color> --books <ids> --json.
4. Report the book title, code, HEX, Lab, Delta E00, target use, and medium.
5. State that matching used CIEDE2000 and is not the same as Pantone Connect proprietary matching.

Compact agent query:

pantone-cli match "#0014DC" --books pantoneSolidCoated,pantoneSolidUncoated --json --no-relationships

Full agent query with shades and harmonies:

pantone-cli match "#0014DC" --books pantoneSolidUncoated --json

Index Discovery

Commands find the offline index in this order:

| Priority | Source | | --- | --- | | 1 | --index <file> | | 2 | PANTONE_INDEX | | 3 | ./pantone-match-index.json | | 4 | ~/.pantone-cli/pantone-match-index.json (installed by fetch-index and index) |

Use a custom index:

PANTONE_INDEX=/path/to/pantone-match-index.json pantone-cli match "#0014DC"
pantone-cli match "#0014DC" --index /path/to/pantone-match-index.json

All persistent data lives under ~/.pantone-cli/ (override with PANTONE_CLI_HOME):

~/.pantone-cli/
  pantone-match-index.json   Active match index (fetched or self-built).
  export/                    Raw Pantone Connect export checkpoints (BYOD only).

The location is resolved from the OS user profile, so it works the same on macOS and Linux (~/.pantone-cli) and Windows (C:\Users\<name>\.pantone-cli). Set PANTONE_CLI_HOME to relocate it.

Index Data

The default index is published as a versioned artifact on GitHub Releases at malhashemi/pantone-cli-index: a gzipped index file plus a manifest.json carrying its version, schema version, and sha256 checksum. fetch-index downloads the manifest, verifies the checksum, and installs the index into ~/.pantone-cli/.

Point at a different (for example, team-hosted) index with either:

pantone-cli fetch-index --url https://your-host.example.com/pantone/manifest.json
PANTONE_INDEX_URL=https://your-host.example.com/pantone/manifest.json pantone-cli fetch-index

The published index contains data derived from Pantone Connect. It is not covered by this repository's MIT license, and no redistribution rights are granted. Download and use it only if you are licensed to use Pantone data. Alternatively, build your own index from your own Pantone Connect account (next section).

Bring Your Own Data

If you have a Pantone Connect account, you can build your own index instead of downloading the published one.

Provide your token, either in the environment or in a .env file in the working directory (cp .env.example .env):

PANTONE_TOKEN="<Pantone Connect access token>"
PANTONE_API_URL="https://api.pantone.com/"

Export the catalogue and build the index (defaults write to ~/.pantone-cli/):

pantone-cli export --rps 75 --concurrency 8
pantone-cli index

Verify:

pantone-cli books --json
pantone-cli match "#0014DC" --books pantoneSolidUncoated --json --no-relationships

The raw export writes resumable checkpoint files:

~/.pantone-cli/export/books.json
~/.pantone-cli/export/books/<bookId>.json
~/.pantone-cli/export/relationships/<bookId>.json
~/.pantone-cli/export/catalogue.json

The index normalizes relationships into color references so runtime matching does not load the large raw export.

Sharing an index with a team

publish-index packages the active index as a distributable artifact — a gzipped index plus a manifest.json with a sha256 checksum:

pantone-cli publish-index                                    # writes ./dist-index/
pantone-cli publish-index --github your-org/your-index-repo  # also uploads to a GitHub release (needs GITHUB_TOKEN)

Host the two files anywhere static, then teammates run:

pantone-cli fetch-index --url https://your-host.example.com/pantone/manifest.json

Probe the raw API response shapes during development:

bun run probe books
bun run probe book pantoneSolidCoated --sample-colors 2
bun run probe shades "11-4201 TCX"
bun run probe harmony "11-4201 TCX" ANALOGOUS

Development

Install dependencies:

bun install

Run from source:

bun run cli --help
bun run match "#0014DC"
bun run books --json

Typecheck and test:

bun run typecheck
bun test

Build the npm binary:

bun run build

Check bundle output:

bun run check

Inspect package contents:

npm pack --dry-run

Publishing

The package exposes this binary:

{
  "bin": {
    "pantone-cli": "./dist/cli.js"
  }
}

Before publishing, verify that npm pack --dry-run includes dist/cli.js and does not include any data files — the package is code-only by design.