CLI

The Voidhash CLI manages your projects from the terminal: people and their access, products and perks, store connections, paywalls, flags, experiments, analytics, webhooks, push notifications and your team. It also connects an app to a project, keeps its generated types current and builds custom paywall components. Commands lists every command by group.

Install

The CLI isn't published to a package registry yet, so npx voidhash-cli and npm install voidhash-cli don't work. Until it is, Studio, the MCP server and the HTTP API do everything the CLI changes, except generating types (init, types) and the component dev loop (dev, new, test).

With access to the source repository, you can build the CLI yourself. You need Node.js 24 or later and pnpm 11; corepack enable provides the pnpm version the repository names.

git clone https://github.com/voidhashcom/voidhash.git
cd voidhash
pnpm install
pnpm --dir apps/cli build

The build writes a single file, apps/cli/dist/bin.cjs. Link it into a directory on your PATH, such as ~/.local/bin, under both of its names, voidhash and voidhash-cli:

ln -s "$PWD/apps/cli/dist/bin.cjs" ~/.local/bin/voidhash
ln -s "$PWD/apps/cli/dist/bin.cjs" ~/.local/bin/voidhash-cli
voidhash --version

To update, run git pull and the two pnpm commands again. The React Native Metro plugin finds voidhash-cli on your PATH.

Sign in

voidhash login

login prints a code and opens your browser. Check that it shows the same code, then choose Confirm code. Turn on Read-only on that page, or run login --read-only, to let the CLI read but never change anything. From then on the CLI acts as you, with your role in every team and project you belong to.

Without a display, such as over SSH or in a container, or with --no-browser, open the printed address on any device, such as your phone, and enter the code.

The CLI appears in Personal settings → Devices and apps in Studio, named after your computer. There you can make it read-only or disconnect it. A sign-in unused for 90 days ends on its own.

A token is only ever sent to the API server that issued it; see where the CLI keeps it. To use another server, such as a self-hosted one, set up a profile.

Run in CI

Unattended jobs use a project secret key instead of a sign-in. Pass it in the environment; the CLI has no flag for a key, so it never lands in your shell history.

VOIDHASH_API_KEY="$VOIDHASH_SECRET_KEY" voidhash product list --json

Build the CLI in the job as in Install, or call the HTTP API directly.

A secret key belongs to one project, so commands act on that project, within the key's access.

Connect an app

Run init in your app's root to connect it to a project:

voidhash init

init signs you in if needed, asks for a team and project, and writes three files: voidhash.config.ts (or .js) naming the project, an SDK client in src/lib/voidhash.ts (or lib/ without a src folder) with the production publishable key, and the type declarations in voidhash.gen.d.ts. It prints the test publishable key for debug and staging builds, then offers to connect your AI agents.

Regenerate the declarations after you change products, perks or locations in Studio, and commit them. types check fails when the committed file is behind the project, which suits CI:

voidhash types generate
voidhash types check

Choose a project

A command that works in a project acts on the first of these:

1. the project --project names: its slug, team/slug, name or ID;
2. the current directory's project: the one its voidhash.config.ts names, or the one you linked this directory, or a directory above it, to;
3. your default project, chosen with switch;
4. the only project you can use.

When none applies, the CLI asks in a terminal and fails with the list of projects otherwise.

voidhash link acme/my-app   # this directory and below
voidhash switch acme/web    # everywhere else
voidhash status             # which project applies here, and what its setup still needs

Links and the default project are kept in your CLI settings, not in the repository, so teammates can work in their own projects. voidhash.config.ts names an app's project for everyone.

Team commands (member, notices, project list and project create) take --org instead, a team's slug, name or ID. It defaults to the team of the current project.

Commands

Commands read voidhash <noun> <verb> [arguments] [flags]. Run any of them with --help for its full flags, or a noun alone to list its verbs. Arguments in [brackets] are optional: in a terminal the CLI asks for them. Most nouns also answer to their plural, such as products.

• Sign-in and projects: init, login, status, link, switch, open, org, project.
• People and access: person, sandbox.
• Catalog and payments: product, perk, provider.
• Paywalls and components: paywall, location, dev, new, publish, test, registry.
• Flags and experiments: flag, experiment.
• Analytics and ads: events, insights, analytics, ads.
• Webhooks and push: webhook, push.
• Team and settings: member, settings, domain, key, audit, notices, feedback.
• Types, API and config: types, mcp, api, config.

Name things the way you know them: a product, perk, paywall or location by slug, name or ID; a person by email, distinct ID or person ID; a webhook by name, URL or ID; a flag by key. When a name matches several things, the command lists them with their IDs. Flag commands also accept a prefix for a person: email:, distinct_id:, person_id: or external_id:.

Scripts and output

Pass --json for the API objects, the stable shape to parse, or --quiet (-q) for IDs only. In scripts, a missing value fails instead of asking, and a change that asks first needs --yes. CLI reference lists the common flags, confirmations and exit codes.

voidhash person find ada@example.com -q | xargs voidhash person view --json

Connect AI agents

voidhash mcp install

mcp install finds Claude Code, Cursor, Codex, VS Code and Claude Desktop on your computer and adds the Voidhash MCP server to the ones you choose; --yes adds it to all of them. It writes no keys: each agent signs in through your browser the first time it uses Voidhash.

Troubleshooting

• voidhash: command not found. Link the built file into a directory on your PATH; see Install.
• Not signed in (exit code 3). Run voidhash login. whoami shows which server the CLI uses; a profile or VOIDHASH_API_URL pointing elsewhere needs its own sign-in. When VOIDHASH_API_KEY is set, it wins, so check that key.
• The code expired, or you cancelled. Run login again for a new code.
• "Which project?" Pass --project, link the directory or switch your default.
• A change is refused. The CLI may be read-only: check Personal settings → Devices and apps. Otherwise your role, or the secret key's access, doesn't include it.
• voidhash.config.ts not found. Run voidhash init in the app's root.
• Something else fails. Run it again with --debug for the full error.

Next steps

• Sign-in and projects: the first commands to run.
• MCP server: let an AI agent work in Voidhash.
• API keys: create a secret key for CI.