Shaders CLI

Install shaders and presets into your codebase as component files, and keep them in sync with the design editor.

The CLI works with any Shaders account for the shaders you save yourself. Installing presets from the library requires Shaders Pro.

Every command runs through npx shaders, so there's nothing to install globally. Run it bare for the guided flow:

npx shaders

It reads your project first and shows what it found: the framework, whether this codebase is connected to a Shaders project, how many shaders are installed and whether any changed in the editor, and whether the agent skill and MCP are in place. On a fresh project it installs the package and writes the config before asking anything. Then one question: find a preset to drop in, install a shader from your project, open the design editor, install the agent skill, or install the MCP. Searching, the skill and the MCP never ask you to sign in. Opening the editor does, since it connects this codebase to a project you own.

In a script or CI, bare npx shaders prints the help instead. Two commands connect a project and install a preset:

npx shaders connect
npx shaders install offsets-1

Setting up a project

Run connect once inside your project:

npx shaders connect

It detects your framework from package.json (Next.js, Nuxt, SvelteKit, SolidStart, Remix, Astro, Vite and plain React, Vue, Svelte or Solid). It then adds the shaders package with the project's package manager and writes a shaders.config.ts:

import { defineConfig } from 'shaders/config'

export default defineConfig({
  framework: 'react',
  project: '4a1e…',                 // the Shaders project this codebase is connected to
  outDir: 'src/components/shaders', // where installed components land
})

Next, connect opens your browser to sign in and asks which Shaders project this codebase belongs to. Pick an existing one or create a new one. A project is a canvas in the design editor that holds any number of shaders. Connecting one tells install and update where to look.

Last, connect adds the Shaders agent skill to the coding agents it finds in your project, so they know the component library and these commands. Pass --no-skill to leave it out.

outDir follows your framework's conventions, and you can change it any time:

• Nuxt: components/shaders, so files auto-import as <ShadersName />.
• SvelteKit: src/lib/components/shaders.
• Remix and React Router: app/components/shaders.
• Everything else: src/components/shaders. Without a src/ directory, app/components/shaders if there's an app/ directory (except in Next.js), otherwise components/shaders.

You can skip connect. Running install in a project that hasn't been set up walks you through it.

Installing shaders

Pass an id, a preset name, or nothing at all:

npx shaders install              # pick from the shaders in your connected project
npx shaders install --all        # install every shader in the project
npx shaders install 4728995      # one of your saved shaders, by id
npx shaders i offsets-1          # a preset, by name (i is short for install)

Each install writes one component file into outDir and records it in shaders.lock.json next to your config. The file holds the full component tree with every prop inline, the same code the editor's Export Code dialog produces. It's ordinary source you own: change the props, wire them to state, compose it with other effects.

The id of a saved shader is shown in the design editor's Export Code dialog. With no id, install lists the shaders in your connected project and lets you choose.

Installing presets

Presets from the library install by name or by id. The name is the collection slug plus the variant number, as shown on each preset page:

npx shaders install offsets-1
npx shaders install offsets      # pick a variant

With Shaders Pro, the preset is first added to your connected project as a saved shader, then installed from that copy. The file then tracks something you can open in the design editor, tweak, and pull back into your codebase with update. Installing the same preset again refreshes that copy instead of adding another.

Without Pro, the CLI says the preset requires a subscription and offers three choices:

• Get Pro: opens the pricing page.
• Sign in: use an existing account that has Pro (offered when you're signed out).
• Install a watermarked preview: a small component that renders the preset live with a watermark, so you can see it in place.

Once your account has Pro, npx shaders update swaps the preview for the real component and adds the preset to your project. You don't need to reinstall.

Searching the library

Describe the look you want and the CLI searches the preset library, the same index the presets page uses:

npx shaders search "liquid chrome hero background"
npx shaders search glass logo --limit 3

Each result prints its name, a short description, how closely it matched, and a short link (shaders.com/p/<name>) your terminal can open. A last link opens the presets page filtered to the same search, with every result rendering live. Open one on shaders.com from the terminal, then install it:

npx shaders preview offsets-1
npx shaders install offsets-1

Searching is free and needs no sign-in. Pass --json to get the results as JSON, which is what a coding agent reads.

Keeping shaders up to date

Run update for every installed shader, or pass an id for one:

npx shaders update               # refresh every installed shader
npx shaders update 4728995       # only that shader

update fetches the current version of each installed shader and rewrites its file when the source changed in the editor. Files you've edited by hand are left alone and reported, so your changes are never silently overwritten. Pass --force to replace them anyway. The same flag works with install.

If a shader has been deleted from Shaders, update says so and leaves the local file untouched. Remove its entry from shaders.lock.json to stop tracking it.

Opening the editor

Open your connected project in the design editor:

npx shaders open

Signing in

Sign in or out explicitly with:

npx shaders login
npx shaders logout

Sign-in happens in your browser and is stored in ~/.shaders/credentials.json, so you sign in once per machine. logout removes it.

Using the CLI in CI and agents

Set SHADERS_API_KEY to a personal API key where there's no browser. Every command then uses the key instead of the browser flow. Any signed-in Shaders account can create keys here:

Pass the key as an environment variable:

SHADERS_API_KEY=your_api_key npx shaders update

Keep the key out of source control: it's tied to your account. You can revoke it from the same panel.

Installing the MCP server

The CLI also installs the Shaders MCP server and the agent skill into your coding agents:

npx shaders install-mcp
npx shaders skill

Reference

Troubleshooting

"… requires a Shaders Pro subscription": the preset is part of the Pro library. Choose an option from the menu, or run npx shaders login if you're signed in to the wrong account.

"… has been deleted from Shaders": the shader or project the command refers to no longer exists. Remove the shader from shaders.lock.json, or run npx shaders connect to pick a different project.

"… has local edits": you changed the file since it was installed. The CLI won't overwrite it unless you pass --force.

Couldn't reach Shaders: browser-based sandboxes such as StackBlitz route network calls through the browser, and can't open a sign-in tab for you. Copy the printed URL into a tab to sign in.

Next steps

• Shaders MCP: connect your coding agent so it can install and edit shaders for you.
• Agent skill: what connect adds to your coding agents, and how to add it on its own.
• Dynamic props: drive an installed shader's props from the mouse or animate them.
• Performance: what each layer costs and how to keep effects fast.