CLI — Voidhash Docs

The Voidhash CLI, voidhash-cli, connects a local project to Studio and keeps generated types in sync. It is not a dependency of the SDK, so you can run it directly without installing anything.

Print the available commands to confirm it runs:

npx voidhash-cli --help

pnpm dlx voidhash-cli --help works the same way. Running the CLI this way keeps it out of your app's dependency tree, so it cannot affect your bundle or lockfile resolution.

Install it as a dev dependency

Install the CLI when you run it often, and always when you use the Metro plugin. The plugin spawns voidhash-cli types generate --watch alongside the Metro dev server and looks up the binary on PATH. A dev-dependency install puts it there.

npm install voidhash-cli --save-dev

Then wrap your Metro config with the plugin:

metro.config.js

const { getDefaultConfig } = require("expo/metro-config");
const { withVoidhash } = require("@voidhash/react-native/metro");

module.exports = withVoidhash(getDefaultConfig(__dirname));

If the binary is not on PATH, withVoidhash prints a warning and returns the Metro config unchanged. The dev server still starts.

Commands

Run each command as npx voidhash-cli <command>.

Command	Use
`init`	Sign in, select a project, and create local config, client, and generated types.
`auth login`	Sign in through the browser.
`auth status`	Show the current CLI identity.
`auth logout`	Remove the stored login.
`auth token --project <slug>`	Print headers for MCP or another authenticated tool.
`types generate`	Refresh `voidhash.gen.d.ts` from the project schema.
`types check`	Fail when committed types are behind the server schema.
`config`	Inspect or change CLI URLs, credentials, and profiles.
`dev`, `new`, `publish`, `test`	Develop and publish paywall components. See below.
`registry ...`	Share, install and manage your organization's components. See below.

Initialize an app

Run init from the app root to connect it to a project:

npx voidhash-cli init

The command is interactive. It creates voidhash.config.ts, src/lib/voidhash.ts, and voidhash.gen.d.ts. It does not install packages or create a local schema.

Keep types in sync

After the project schema changes in Studio, regenerate the declaration file:

npx voidhash-cli types generate

Commit the generated declaration. To catch Studio changes that nobody has pulled into the repository yet, add a check to CI:

npx voidhash-cli types check

The check fails when the committed types are behind the server schema.

Components

These commands work on your project's paywall components. Run dev, new and publish in your app's root, signed in with auth login:

Command	Use
`dev`	Keep a working copy of the project's components in `.voidhash`, build them as you edit, and show the builds in the paywall editor.
`new <name>`	Create a component with its editor panel in the working copy.
`publish`	Publish new and changed components as new versions; `--all` or `--component <slug>`, and `--yes` to skip the prompt.
`test [component\|path]`	Run the checks publishing runs on a component, a crate or a module; `--panel` names a panel module.

Develop a component walks through them in the order you use them.

Your organization's components

The registry commands manage the components your organization shares across its projects. Commands that take a [path] use the current directory when you leave it out:

Command	Use
`registry list`	List project, installed and organization components, with owners, updates and warnings.
`registry publisher show` / `claim <name>`	Show or claim your organization's namespace.
`registry publish [path]`	Publish a bundle, or `--from-project <slug>@<version>`, to your organization.
`registry install <id>`	Install a component; `--yes` accepts its review.
`registry update <id>`	Move an install to the newest version in its range.
`registry uninstall <id>`	Remove an installed component.
`registry deprecate <id> [version]`	Deprecate a version or a whole component; `--undo` lifts it.
`registry yank <id> <version>`	Yank a version for good.
`registry transfer <id>`	Make the project the owner of a component (organization admins).

See Publishing and Installing.

Profiles

A profile keeps environment-specific CLI settings separate. Set a value under a profile, then pass the same profile to later commands:

npx voidhash-cli config set api_url https://example.test --profile staging
npx voidhash-cli types generate --profile staging

The base configuration lives in ~/.voidhash. Project selection lives in the committed voidhash.config.ts.

Troubleshooting

Not logged in. Run npx voidhash-cli auth login.
Project config missing. Run npx voidhash-cli init from the app root.
The paywall editor does not show your local builds. Check that voidhash-cli dev is running and that you opened the editor signed in as the same person, in the project voidhash.config.ts names. If the browser asked to let the site reach devices on your local network, allow it.
Generated types are stale. Run npx voidhash-cli types generate and commit the file.