tastehq 0.1.0

One-liner CLI to pipe any brand's DESIGN.md from TasteHQ to stdout

tastehq (Python)

One-liner CLI to pipe any brand's DESIGN.md from tasteHQ to stdout. Also scores URLs against brand grammars, ingests external URLs into the grammar, and bootstraps AGENTS.md for any project that wants to anchor its agentic workflows to a brand's taste.

Install

The PyPI package will land with v1.0 — pip install tastehq will work then. Until then, editable install from source:

git clone https://github.com/MustBeSimo/tasteHQ.git
cd tasteHQ
pip install -e cli/python

That registers the tastehq binary on your PATH.

Usage

tastehq <slug>                          Print brand DESIGN.md to stdout
tastehq <slug> --json                   Print full JSON entry
tastehq list                            List all brands (tab-separated)
tastehq list --mood <mood>              Filter list by mood tag
tastehq search <query>                  Lexical search across the catalog
tastehq diff <slug1> <slug2>            Markdown table comparing two brands
tastehq judge <url> --target <brand>    Score URL against a brand's grammar
tastehq import <url>                    Extract URL → grammar v2 vector
tastehq init <slug>                     Bootstrap AGENTS.md in current dir
tastehq --help                          Show help

Examples

# Pipe Stripe's design doc to stdout
tastehq stripe

# Full JSON entry
tastehq stripe --json

# List all brands
tastehq list

# Filter by mood
tastehq list --mood editorial

# Search
tastehq search "warm beige"

# Diff two brands
tastehq diff stripe linear

# Score a URL against Stripe's grammar
tastehq judge https://example.com --target stripe

# Ingest any URL into a grammar v2 vector
tastehq import https://example.com

# Pipe into a file
tastehq anthropic > anthropic-design.md

# Run without install
python cli/python/tastehq_cli.py stripe

Bootstrap AGENTS.md

tastehq init <slug> writes a ready-to-commit AGENTS.md to the current directory, declaring the brand whose taste your agentic workflows should target. The file is the canonical contract between your repo and any AI coding agent reading it — see the AGENTS.md spec.

# Bootstrap AGENTS.md for Stripe in the current directory
tastehq init stripe

# Custom output path
tastehq init stripe --out docs/AGENTS.md

# Overwrite an existing file
tastehq init stripe --force

# Print to stdout instead of writing (pipe-friendly)
tastehq init stripe --print | less

# Also install the Claude Skill at .claude/skills/tastehq.md
tastehq init stripe --skill

Exit codes:

Code	Meaning
0	Wrote AGENTS.md successfully
1	Output file exists (re-run with --force)
2	Brand slug not found in the catalog
3	Network error reaching tasteHQ

The write is atomic (tempfile + os.replace) so a failed or interrupted run never leaves a half-written file on disk.

Requirements

• Python >= 3.8
• No external dependencies (stdlib only — urllib.request, tempfile, os)

API

Wraps the public tasteHQ API at https://taste-hq.vercel.app/api:

Endpoint	Description
/api/styles.json	Full catalog
/api/styles/:slug.json	Single brand JSON
/api/styles/:slug/design.md	Brand DESIGN.md
/api/styles/:slug/agents.md	Ready-to-commit AGENTS.md
/api/score	URL + target_brand → per-axis judge score
/api/extract	URL → grammar v2 vector

Publish checklist (v1.0)

• pip install build twine
• python -m build
• twine upload dist/*
• Tag release: git tag v1.0.0 && git push --tags