Vault CLI

Creative code should not arrive wearing a disguise.

The Hyperiux Vault CLI adds creative interaction patterns directly into your project as source files. No hidden runtime. No locked component package. No motion logic living somewhere you cannot inspect.

Use it to install scroll effects, cursor systems, text animations, page transitions, WebGL scenes, navigation patterns, backgrounds, buttons, and microinteractions with local code ownership.

Small details. Big “who built this?” energy.

CLI Package

The CLI package is hyperiux.

Use it with npx:

npx hyperiux --help

For most projects, you do not need to install the CLI globally. Running it with npx keeps the command fresh and avoids version drift across machines.

Quick Start

Initialize Vault in your project.

npx hyperiux init

Add an effect.

npx hyperiux add scroll-stack

Run your app.

npm run dev

Check your setup.

npx hyperiux doctor

Then inspect the generated files, tune the motion, test the page, and commit the result.

Requirements

Vault effects are source-first. That means the CLI writes files into your workspace instead of hiding them inside a package.

That is the point. You get the code. You own the edits.

Command Reference

Help Commands

Use help when you need the shape of a command without opening the docs.

npx hyperiux --help
npx hyperiux add --help
npx hyperiux doctor --help
npx hyperiux upgrade --help

Global Options

Use --verbose when reporting issues or debugging registry, dependency, or file-generation problems.

Exit Behavior

The CLI exits with a non-zero status code when a command fails. This makes it usable inside CI checks and automated workflows.

Common failure cases include:

• invalid effect name
• missing package manager
• registry request failure
• missing Pro authentication
• dependency installation failure
• unsupported project structure
• file conflict during install or upgrade
• missing write permission in the target directory

The CLI prints the failed step, the likely cause, and the next action where possible.

It is a flashlight. Not a priest.

init

Prepares your project for Vault effects.

npx hyperiux init

The init command creates or updates the local configuration used by Vault.

It sets where generated files should go and how the CLI should resolve project aliases, utilities, styles, and component paths.

Typical configuration includes:

• component output path
• utility alias
• Tailwind CSS entry path
• package manager detection
• registry configuration
• project framework detection

Example configuration:

{
  "style": "default",
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@hyperiux": "https://vault.hyperiux.com/r/{name}.json"
  }
}

Adjust aliases to match your project.

If your components live somewhere else, tell Vault where the floor is.

add

Adds an effect to your workspace.

npx hyperiux add [effect-name]

Example:

npx hyperiux add scroll-stack

Each effect includes a manifest. The CLI reads that manifest and adds only the files required for the selected effect.

Depending on the effect, the command adds:

• React components
• hooks
• utility files
• styles
• shaders
• animation setup
• dependency notes
• usage examples

The CLI also checks the effect manifest for required dependencies.

If the selected effect requires packages such as GSAP, Motion, Three.js, or React Three Fiber, the CLI makes those requirements visible during installation.

No drive-by Three.js.

upgrade

Updates an installed Vault effect.

npx hyperiux upgrade [effect-name]

Example:

npx hyperiux upgrade scroll-stack

Vault effects are editable source files. That makes upgrades more sensitive than normal package updates.

The upgrade command checks the installed effect against the latest registry version and protects local changes before replacing files.

Recommended upgrade flow:

git status
npx hyperiux upgrade scroll-stack --check
npx hyperiux upgrade scroll-stack --diff
npx hyperiux upgrade scroll-stack
git diff

Upgrade Safety Options

By default, upgrades should not silently overwrite modified local files. If an effect file has been edited, the CLI warns before replacing it.

Source ownership is useful only if updates respect the source.

uninstall

Removes an installed effect.

npx hyperiux uninstall [effect-name]

Example:

npx hyperiux uninstall scroll-stack

The command removes effect-owned files listed in the effect manifest.

Shared files are preserved when they are used by other installed effects.

Typical removals include:

• effect component files
• effect-specific hooks
• effect-specific styles
• effect-specific shader files
• generated usage examples

The command does not remove dependencies automatically if those dependencies may still be used elsewhere in your project.

Dependency removal should be deliberate.

No one wants an uninstall command that behaves like a raccoon in a server room.

list

Lists installed Vault effects.

npx hyperiux list

Example output:

Installed Vault effects

scroll-stack
  version: 1.0.0
  path: components/hyperiux/scroll-stack.tsx
  dependencies: gsap

kinetic-header
  version: 1.2.0
  path: components/hyperiux/kinetic-header.tsx
  dependencies: motion

Use this when you need to see what Vault has added to the project.

It is especially useful before upgrades, audits, and cleanup.

doctor

Diagnoses Vault setup issues.

npx hyperiux doctor

The doctor command checks common integration problems.

It can report:

• missing dependencies
• broken import aliases
• missing Tailwind content paths
• missing CSS entry files
• missing "use client" boundaries
• browser-only code used in server components
• duplicate effect files
• unsupported project structure
• registry access issues
• Pro authentication problems
• WebGL or canvas setup warnings

Example output:

Hyperiux Doctor
Project detected: Next.js
Tailwind config found
Components alias resolved
Missing dependency: gsap
scroll-stack uses browser APIs and should be rendered inside a client boundary
Next steps:
npm install gsap
Add "use client" to the component entry file.

Run doctor after installing effects, upgrading effects, or moving files manually.

It will not fix your taste. It will fix a surprising number of setup issues.

env

Prints environment details.

npx hyperiux env

Use this when debugging or reporting an issue.

Example output:

Hyperiux environment
CLI: 1.0.0
Node: 20.11.0
Package manager: pnpm
Framework: Next.js 15
React: 18.3.1
Tailwind: 4.0.0
OS: macOS
Project root: /site

The env command helps identify version mismatches, package manager issues, and framework-specific behavior.

A repo with three package managers is not a tech stack. It is a cry for help.

auth

Connects Pro or private registry access.

Use interactive login when possible.

npx hyperiux auth login

The CLI prompts for your access token and stores it according to your local configuration.

Avoid passing tokens directly in terminal commands unless your team accepts shell history exposure.

Prefer this:

npx hyperiux auth login

Instead of this:

npx hyperiux auth hvlt_************************

For CI, use an environment variable.

HYPERIUX_TOKEN = hvlt_xxx npx hyperiux add pro-effect

Do not commit access tokens. Do not place tokens inside public config files. Do not paste tokens into issue threads.

The internet has enough haunted secrets.

Dependency Behavior

Vault resolves dependencies per effect.

That means the CLI does not install every possible animation and rendering package up front.

Some effects need only React and CSS. Some need GSAP. Some need Motion. Some need Three.js, React Three Fiber, shaders, canvas utilities, or browser APIs.

The effect manifest declares the required dependencies. The CLI reads that manifest and reports what the selected effect needs.

This keeps your project cleaner and reduces unused creative machinery.

Motion should earn its place in the bundle.

Upgrade Safety

Because Vault writes source files into your project, upgrades should be handled with care.

Before upgrading:

git status

Check what will change:

npx hyperiux upgrade scroll-stack --dry-run

Preview the diff:

npx hyperiux upgrade scroll-stack --diff

Then upgrade:

npx hyperiux upgrade scroll-stack

After upgrading:

git diff

If you heavily customized an effect, review the update manually before accepting changes.

The CLI can help you move faster.

It should not make decisions for your codebase while you are looking away.

Global Installation

You can install the CLI globally if your team prefers.

npm install -g hyperiux

Then run:

hyperiux --help

Global installation can be useful for frequent usage, but it can create version drift between team members.

For shared projects, prefer npx or pin the CLI version in project scripts.

npx hyperiux@latest add scroll-stack

Or:

{
  "scripts": {
    "vault:add": "hyperiux add",
    "vault:doctor": "hyperiux doctor"
  }
}

Version Check

Print the current CLI version.

npx hyperiux --version

Or:

npx hyperiux -v

Use this when debugging registry behavior, command output, or compatibility issues.

Troubleshooting

Command Not Found

Use npx.

npx hyperiux --help

If using a global install, reinstall the CLI.

npm install -g hyperiux

Effect Not Found

Check the effect name.

npx hyperiux list

For registry effects, confirm the registry configuration and network access.

Missing Dependency

Install the dependency reported by the CLI.

npm install gsap

Then run:

npx hyperiux doctor

Import Alias Does Not Resolve

Check your project aliases.

Common aliases include:

• @/components
• @/lib/utils
• @/hooks

Update the generated imports or your TypeScript path mapping.

Tailwind Styles Do Not Apply

Check that Tailwind scans the folder where Vault files were added.

Example:

export default {
  content: [
    "./app/**/*.{ts,tsx}",
    "./pages/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./components/hyperiux/**/*.{ts,tsx}"
  ],
  theme: {
    extend: {}
  },
  plugins: []
};

If the classes are not compiling, Tailwind probably does not know the files exist.

Hydration Warning

Check whether the effect uses browser-only APIs.

If it uses window, document, pointer movement, scroll position, layout measurements, canvas, or WebGL, it probably needs a client boundary.

"use client";

For heavier effects, use dynamic imports.

import dynamic from "next/dynamic";
const WebGLBackground = dynamic(
  () => import("@/components/hyperiux/webgl-background"),
  { ssr: false }
);

Servers are many things.

They are not GPU theatres.

Upgrade Conflict

Check local changes.

git status

Preview the upgrade.

npx hyperiux upgrade scroll-stack --diff

If your local version is heavily customized, copy the updated effect into a temporary branch and merge by hand.

Taste is local.

So are merge conflicts.

Pro Effect Fails to Install

Check authentication.

npx hyperiux auth login

Then run:

npx hyperiux doctor

In CI, confirm that HYPERIUX_TOKEN is available to the command.

Recommended Workflow

For most teams:

npx hyperiux init
npx hyperiux add scroll-stack
npm run dev
npx hyperiux doctor

Then:

• Inspect the generated files.
• Read the implementation notes.
• Tune the effect.
• Test mobile behavior.
• Check reduced motion.
• Profile performance.
• Review accessibility.
• Commit the source.

That is the workflow. Install the effect. Own the files.

Command Summary

Copy the code. Tune the motion. Ship the moment.