@loftlyy/cli

Simple CLI for querying Loftlyy brand data.

Install and Use

npm i -g @loftlyy/cli

Or run without installing:

npx @loftlyy/cli list

Quick examples:

loftlyy list
loftlyy search apple
loftlyy get apple
loftlyy palette apple --output json

Command Reference

• loftlyy list [--limit <n>] - list brands (summary rows)
• loftlyy get <slug> - get one brand object
• loftlyy search <query> - full-text and hex-token search
• loftlyy filter [options] - facet filtering (--industry, --tag, --color-family, --typography-style, --q)
• loftlyy similar <slug> [--limit <n>] - similar brands
• loftlyy palette <slug> - palette JSON/table for one brand
• loftlyy facets - available filter values

Legacy namespace is still supported:

• loftlyy brands ...
• loftlyy b ...

Global Options

• --source <local|remote> - where to load data from
• --base-url <url> - remote base URL override
• --output <table|json|ndjson> - output format
• --strict - fail fast on invalid brand data
• --no-color - disable ANSI colors

Data Source Behavior

The CLI auto-detects default source:

• if data/brands exists in the current working directory -> local
• otherwise -> remote

Remote mode uses:

• default base URL: https://loftlyy.com
• endpoint: GET /api/cli
• response shape: { "brands": Brand[] }

You can override the host:

loftlyy --source remote --base-url https://staging.loftlyy.com list

How It Works

• local source: scans data/brands/*.ts (excluding index.ts), validates entries, then builds search/facet indexes.
• remote source: fetches GET /api/cli, validates each brand entry, then builds the same indexes.
• search is case-insensitive.
• slug commands (get, similar, palette) are case-insensitive.
• filter values are case-insensitive.

Maintainer Guide

Prerequisites

• Node 20+
• npm account with publish access to @loftlyy/cli

Build the CLI package

From repository root:

pnpm cli:build

Or directly:

npm --prefix cli run build

Build output is cli/dist/.

Bump Version

CLI package version lives in cli/package.json.

Patch:

npm --prefix cli version patch

Minor:

npm --prefix cli version minor

Major:

npm --prefix cli version major

If you do not want git tags/commits created automatically, use --no-git-tag-version.

Publish to npm (manual)

1. Ensure you can publish the scope/package:

npm whoami

2. Build:

npm --prefix cli run build

3. Publish:

npm --prefix cli publish --access public

Auth Token Setup

Local machine (recommended interactive setup):

npm login

CI setup (token-based):

1. Create an npm automation token in npm account settings.
2. Store it as NPM_TOKEN in CI secrets.
3. Configure npm auth in CI before publish:

echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc

Then run:

npm --prefix cli publish --access public

Release Checklist

1. Confirm /api/cli is deployed and returning { brands: [...] }.
2. Run checks:

pnpm typecheck
pnpm dlx oxlint cli app/api/cli/route.ts
npm --prefix cli run build

3. Bump cli/package.json version.
4. Publish @loftlyy/cli.
5. Smoke test:

npx @loftlyy/cli list
npx @loftlyy/cli search apple
npx @loftlyy/cli get apple