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.

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.

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.
Generated types are stale. Run npx voidhash-cli types generate and commit the file.