CLI (npx styleref)

npx styleref pulls, initializes, and validates StyleRef styles from the terminal. It’s backed by the REST API, has zero dependencies, and needs Node 18 or newer. Nothing to install — npx runs it.

Commands

pull

Print a style compiled for an AI tool.

npx styleref pull 1an6edgp-c42c0cba5315 --format flux

Takes a style reference — a share slug, a /share URL, or (signed in) your own style’s id — and a --format (default, flux, midjourney, diffusion, stylemd, json).

init

Set a project’s style: write STYLE.md and add a note to AGENTS.md.

npx styleref init 1an6edgp-c42c0cba5315

See Add STYLE.md to a project.

validate

Lint the STYLE.md in the current directory. Offline by default:

npx styleref validate

Add --remote to run the check against the API instead of locally. See Validate & lint.

search

Find public styles.

npx styleref search warm editorial

login

Connect your account so your private styles resolve. Get their ids from GET /me/styles or the style’s URL on styleref.io.

npx styleref login
npx styleref pull e7c1f2a9-2f65-4f0e-9a3d-2b1c4d5e6f70   # your own style, by id

Pulling one of your own styles prints what you last generated on styleref.io, not your live unsaved edits — the same rule the API follows. If you have never generated it, the CLI prints the instruction and exits non-zero:

styleref: This StyleRef hasn't been generated yet — open it on styleref.io and Generate it first.

logout

Remove the stored credentials.

npx styleref logout

The ComfyUI nodes share the same credentials file, so this signs them out too.

Authentication

login runs the OAuth 2.1 flow (authorization code + PKCE, loopback redirect) against styleref.io and stores tokens at:

~/.config/styleref/credentials.json

The file is written with 0600 permissions and holds a refresh token, so the CLI renews its own access token — you don’t re-login every session.

To supply a token another way, set STYLEREF_TOKEN, which overrides the stored credentials. Note that an access token expires in about an hour and this path never refreshes it, so it suits a single CI job rather than a long-lived agent. For an unattended machine, copy the whole credentials.json there instead — it keeps refreshing itself.

Configuration

Next steps

• Add STYLE.md to a project — init in context.
• Authentication & scopes — the OAuth flow login uses.
• Endpoints reference — what the commands call.