auth — Voidhash Docs

The auth command group manages the CLI's authentication. Logging in stores an API key in your CLI configuration, and every other command that talks to the Voidhash API (like types generate or deploy) uses that key. There are four subcommands: login, logout, status, and token.

Starts a browser-based device login:

npx voidhash-cli auth login

The flow works like this:

The CLI starts a local callback server at http://127.0.0.1:4004/callback and generates an 8-character confirmation code.
Your browser opens the Voidhash device authorization page with that code. The CLI also prints the confirmation code and a fallback URL — if the browser doesn't open, copy and paste the URL manually.
Verify that the code shown in the browser matches the one printed in your terminal and approve the login.
The browser redirects back to the local callback server, which hands the CLI an API key. The key is stored as api_key in ~/.voidhash.

If you cancel in the browser, the CLI prints Login cancelled. and nothing is stored. If you are already logged in, the CLI asks for confirmation and logs you out before starting a new login.

Profiles

When you run with --profile <name>, the API key is stored in that profile's overrides instead of the base configuration, so you can keep separate logins per profile (for example a local development environment). See config for how profiles work.

auth logout

Clears the stored API key:

npx voidhash-cli auth logout

If a session exists, the CLI asks for confirmation (You are currently logged in as <name>...) before clearing api_key from the configuration. If no session can be resolved, the confirmation is skipped and the stored key (if any) is cleared directly.

auth status

Shows who you are logged in as:

npx voidhash-cli auth status

Prints Logged in as <name> or Not logged in. If the session can't be fetched (for example the stored key was revoked), the CLI suggests running voidhash-cli auth login again.

auth token

Prints authenticated request headers for the Voidhash MCP server as a single line of JSON:

npx voidhash-cli auth token --project my-app

{"Authorization":"Bearer vh_...","X-Voidhash-Project":"my-app"}

This is designed as a headers helper for MCP clients like Claude Code: the client shells out to the CLI at connection time, so your API key never has to be pasted into an MCP configuration file. It fails with You must be logged in. Run 'voidhash-cli auth login' first. when no key is stored.

The project is resolved in this order:

The --project flag (project id or slug)
The CLAUDE_PLUGIN_OPTION_PROJECT environment variable
The VOIDHASH_PROJECT environment variable

When none of these resolve, the X-Voidhash-Project header is omitted and only the Authorization header is printed. See the MCP page for how to wire this into your MCP client configuration.