config & profiles — Voidhash Docs

Inspect and change the CLI configuration, and use profiles to switch between environments.

The config command group manages the CLI's configuration file, a JSON file stored at ~/.voidhash. It holds three keys:

api_key — the API key stored by auth login. null when you are logged out.
api_url — the Voidhash API endpoint. Defaults to https://api.voidhash.com.
web_url — the Voidhash web app used for browser-based flows like device login. Defaults to https://voidhash.com.

You normally never need to touch api_url or web_url — the defaults point at the hosted Voidhash platform. They exist for self-hosted deployments and for pointing the CLI at a locally running backend during development.

config

Running config with no subcommand prints the resolved configuration:

npx voidhash-cli config

Current configuration:
api_key: (not set)
api_url: https://api.voidhash.com
web_url: https://voidhash.com

Profiles: dev, staging

The output shows each key with its effective value — unset values are marked (not set) — and, when profiles exist, a list of the profile names defined in the file. If a profile is active via --profile <name>, an Active profile: <name> line is printed first and the values shown are the base configuration with that profile's overrides merged on top.

config set

Sets a single configuration value:

npx voidhash-cli config set api_url http://localhost:8787

set takes two positional arguments, key and value. Valid keys are the three configuration fields: api_key, api_url, and web_url. The write is schema-validated — anything else fails with Failed to set configuration.

Prefer auth login for keys

You can set api_key by hand, but the normal way to obtain and store one is the browser-based auth login flow — it writes the key to the same place.

config reset

Restores the configuration to its defaults:

npx voidhash-cli config reset

reset sets api_url and web_url back to their default values but preserves your api_key — resetting the configuration does not log you out. To clear the stored key, use auth logout instead.

Profiles

Profiles let you keep several environments — production, staging, a local backend — in the same ~/.voidhash file and switch between them per invocation. A profile is a sparse set of overrides: it only stores the keys you explicitly set for it, and every other key falls back to the shared base configuration.

On disk, profiles live under a profiles map next to the base keys:

~/.voidhash

{
  "api_key": "vh_...",
  "api_url": "https://api.voidhash.com",
  "web_url": "https://voidhash.com",
  "profiles": {
    "dev": {
      "api_url": "http://localhost:8787"
    }
  }
}

Here the dev profile only overrides api_url; api_key and web_url still come from the base configuration when dev is active.

Selecting a profile

Pass --profile <name> to any command. It is a shared flag, so it works both before and after the subcommand name:

npx voidhash-cli deploy --profile dev

npx voidhash-cli --profile dev types generate

There is no short alias for --profile (-p belongs to studio --port). A profile does not need to be created first — it comes into existence the first time you write to it.

Writing to a profile

When a profile is active, config set (and any other command that persists configuration, such as auth login) writes into that profile's overrides instead of the base configuration. The base values and all other profiles are left untouched.

Resetting a profile

config reset with an active profile clears only that profile's overrides, reverting it to the base configuration:

npx voidhash-cli config reset --profile dev

If the profile has its own api_key override, that key is preserved — same rule as a base reset: resetting never logs you out.

Example: a dev profile against a local backend

A common setup is a dev profile that points the CLI at a locally running Voidhash backend while the base configuration keeps talking to production:

npx voidhash-cli config set api_url http://localhost:8787 --profile dev

Verify what the profile resolves to:

npx voidhash-cli config --profile dev

Active profile: dev
Current configuration:
api_key: vh_...
api_url: http://localhost:8787
web_url: https://voidhash.com

Profiles: dev

From here, run any command with --profile dev to target the local backend — for example voidhash-cli deploy --profile dev — and omit the flag to target production. When the local environment needs its own login, run voidhash-cli auth login --profile dev and the resulting key is stored only in the dev profile.