CLI

Jolocky items are served as standard shadcn registry items, so you install them with the official shadcn CLI. There is no separate Jolocky CLI to install.

Always use https://www.jolocky.com (with www). The apex domain jolocky.com redirects to www, and Node's fetch drops the Authorization header on that cross-origin redirect, so authenticated requests sent to the apex domain fail.

Adding Free Items#

Pass the item's registry URL to the add command. Free items need no account or license key:

pnpmnpmyarnbun
pnpm dlx shadcn@latest add https://www.jolocky.com/r/aurora-drift.json
Copy

The CLI then:

1. Downloads the registry item from Jolocky.
2. Installs any npm packages listed in the item's dependencies. Most items have none; Sonar Terrain lists three.
3. Writes the item's files to components/footers/<item>/ in your project (under src/ if your project uses a src directory).

The three package used by Sonar Terrain does not include TypeScript types. In a TypeScript project, also run npm install -D @types/three.

Adding Pro Items#

Pro items require an active Pro Annual license key. You can find your key in the member dashboard under the License tab.

The shadcn CLI has no flag for license keys. Pass the key in one of these two ways.

Option 1: Key in the URL#

Add your key as the key query parameter. Quote the URL so your shell does not interpret the ?:

pnpmnpmyarnbun
pnpm dlx shadcn@latest add "https://www.jolocky.com/r/golden-hour.json?key=YOUR_LICENSE_KEY"
Copy

This is the quickest option, but the key ends up in your shell history.

Option 2: The @jolocky Namespace#

Add the registry to your components.json:

Copy{
  "registries": {
    "@jolocky": {
      "url": "https://www.jolocky.com/r/{name}.json",
      "headers": {
        "Authorization": "Bearer ${JOLOCKY_LICENSE_KEY}"
      }
    }
  }
}

Put your key in .env.local (or .env) and keep that file out of version control:

CopyJOLOCKY_LICENSE_KEY="YOUR_LICENSE_KEY"

Then install by name:

pnpmnpmyarnbun
pnpm dlx shadcn@latest add @jolocky/golden-hour
Copy

The CLI reads .env.local and .env, and replaces ${JOLOCKY_LICENSE_KEY} with your key. If the variable is not set, the CLI stops with an error asking you to set it in .env or .env.local. See components.json for a free-only setup that needs no key.

If the key is missing, invalid, or expired, the registry responds with 403 and nothing is installed.

File Structure#

Each item installs into its own folder. A typical item looks like this:

• <item>-footer.tsx (registry:block): the main component.
• components/ and icons/ (registry:component): sub-components and inline SVG icons.
• hooks/ (registry:hook): React hooks used by the item, such as animation loops or media queries.
• lib/, styles/, data/, types.ts (registry:lib): helpers, scoped CSS, default content, and prop types.
• index.ts: re-exports the component, so you can import it from @/components/footers/<item>.

The exact files differ per item. The Code tab on each item page shows its file tree.

Overwriting Existing Files#

To replace local files with the current version from Jolocky, use --overwrite. This discards your local edits to those files:

pnpmnpmyarnbun
pnpm dlx shadcn@latest add https://www.jolocky.com/r/aurora-drift.json --overwrite
Copy

Previewing Without Writing#

To see which files and dependencies an item adds before changing your project, use --dry-run:

pnpmnpmyarnbun
pnpm dlx shadcn@latest add https://www.jolocky.com/r/aurora-drift.json --dry-run
Copy