@aperveil/cli

Add editable shader and block source to your project. Only shared infrastructure comes from npm: runtime, React, Vue, element and this CLI. There are no separate Free, Pro, shader or block content packages in this distribution.

npx @aperveil/cli add shader dot-grid
npx @aperveil/cli add block signature-hero --framework vue
npx @aperveil/cli add shader dot-grid --framework html
npx @aperveil/cli add block signature-hero --framework wordpress

React is the default; framework selection is explicit. HTML and WordPress carry standalone browser assets. Serve HTML through a web server. Follow the generated README to install the WordPress plugin.

Free content needs no account. For protected content use npx @aperveil/cli login; the browser device flow never gives the CLI your password or browser session. Pro blocks and their selected shaders are authorized separately. whoami shows your CLI identity and logout removes it. An active applicable grant is required for Pro delivery; these commands do not enable unavailable Pro purchases.

Dependencies and files

Run inside the intended project (inside its child workspace in a monorepo). The CLI detects npm, pnpm, yarn or bun from packageManager and lockfiles, then installs declared public dependencies with that manager. Its normal lifecycle script policy applies. Conflicting manager declarations require an explicit --package-manager npm|pnpm|yarn|bun choice. Ambiguous workspace roots are refused. No private registry or account token is needed by the installed code or builds.

Use --skip-install to write sources and print a manual dependency command. Without package.json, use this files-only option or HTML/WordPress mode. The CLI does not silently create a framework application. Unsupported custom launchers may require running the printed dependency command yourself.

The default destination is src/components/aperveil/<slug> if src exists, otherwise components/aperveil/<slug>. --dir chooses a destination inside the selected project. Shared block files live beside block folders in _shared. CLI delivery uses the default design; use a studio ZIP for your customized design. Load the README's fonts and licensed media and include sources in Tailwind scans.

The CLI verifies the versioned manifest, exact file set, hashes, paths, installed runtime and adapter compatibility before writing. It rejects symlinks, unsafe paths and shared-file conflicts. --force replaces destination files but never bypasses these checks or overwrites shared files with differing content. Compatibility checks inspect node_modules resolution, not custom aliases or PnP.

Installation record

aperveil.lock.json records source revisions, hashes, license metadata, shared ownership and dependency status. It contains no account credentials. Commit it with the installed source. Concurrent installs are refused; an unknown stale .aperveil.install.lock is never silently removed.

If dependency installation fails, sources and a pending record remain, the CLI exits unsuccessfully and prints a retry command. After repairing dependencies, rerun the original add command with --force to verify and refresh the record. No automatic update or merge command is provided.

For local development, set APERVEIL_API_URL=http://localhost:3000. Remote origins require HTTPS. Delivery requests reject redirects.

MCP catalog assistant

Run npx -y @aperveil/cli mcp as a stdio MCP server in your editor (Node.js 20+). The server exposes search_catalog, get_item, and get_installation_guide. Search supports keywords, shader/block kind, Free/Pro tier, framework and pagination. Details include public parameters and previews; guides include the CLI command, dependencies and framework examples. Coming-soon content has no install command.

These tools only read public catalog metadata. They do not read your CLI login, write project files, execute commands or deliver source. Your editor can use the returned guide with its normal command tools and your permission. Install Free content through aperveil add; protected delivery still requires its own login and applicable license. Starting MCP does not enable Pro purchases or access. Protocol messages alone are written to stdout. Close stdin to stop the server.

Optional CLI analytics

CLI product analytics is off until you explicitly enable it:

npx @aperveil/cli telemetry enable
npx @aperveil/cli telemetry status
npx @aperveil/cli telemetry disable

The preference is stored separately from login credentials and survives logout. For one process, APERVEIL_TELEMETRY=1 enables reporting. DO_NOT_TRACK=1 or APERVEIL_TELEMETRY_DISABLED=1 takes priority over any enable preference (true is also accepted). Non-interactive use defaults to off as well.

Reports contain the content identifier, framework, CLI version, source/dependency outcome, duration and categorical failure stage. They contain no account token, project path, source code, command text or raw error message. No persistent CLI visitor ID is created. Reporting is best effort; collector errors never change the installation result. Installed runtimes and adapters do not report usage.