The configuration directory is --config-dir, else VOLTAGE_CONFIG_DIR, else $XDG_CONFIG_HOME/voltage, else ~/.config/voltage. It must be an absolute path. The CLI creates it owner-only (mode 0700 on Unix) and refuses one that is a symlink or owned by another user. voltage context shows which directory is in use and creates nothing.
| Path | Contents |
|---|---|
config.toml |
Saved credentials' non-secret facts (name, kind, store, email, bound organization and environment, auth URL) and profiles. No secrets. |
credentials/ |
Secrets for credentials saved with --credential-store file, one owner-only file each |
credentials.lock |
Serializes login refreshes and credential changes across concurrent commands |
requests/ |
The request journal: each change that carries an ID (a payment, a treasury movement, wallets create --id, or a --data body with an id), with its operation, scope, and request hash, never the body. See payment IDs. |
A credential's secret is kept in one store, chosen when you log in or import a key:
keychain(default): the macOS Keychain, the Linux Secret Service, or the Windows Credential Manager, under the service namevoltage-cli.file: an owner-only file undercredentials/, for machines without an unlocked keychain, such as headless Linux.
A command reads a secret from its store once and keeps it in memory until it exits, because the macOS Keychain can ask for approval on every read. A login refresh reads it again under the credential lock. To stop the prompts, select Always Allow when macOS asks, or log in with --credential-store file.
A profile saves an organization, an environment, and a credential under one name. --profile NAME uses it as a complete configuration; see log in and use profiles.
Related: environment variables, global flags, install.