AI agents: read this documentation natively — index: https://docs.openvoidnet.com/llms.txt, full: https://docs.openvoidnet.com/llms-full.txt, this page: https://docs.openvoidnet.com/docs/cli/authentication.md.
CLI Authentication
Token lifecycle, scopes, profiles, and credential storage for the Voidnet CLI.
Token lifecycle
voidnet login mints a machine token (vnp-pub-*, 30 days) through browser consent, then verifies it against the publisher API before storing anything. A mint that fails verification is rolled back (revoked), never kept. login --token verifies a console-issued token the same way and rejects garbage at the door.
voidnet logout revokes the token server-side first, then wipes local credentials. Revocation is confirmed — a logout that cannot reach the server fails loud instead of pretending.
Scopes
Login grants read and verify scopes only:
| Granted at login | Console only |
|---|---|
apps:read, apps:verify, metering:read, keys:read | apps:publish, keys:rotate |
A 403 insufficient_scope names the missing scope. Re-logging in never grants more — publish and key rotation stay in the console by server design.
Profile and identity
Login stores a profile alongside the token: display name, publisher username, granted scopes, app binding, and expiry. Inspect it with:
voidnet profile
voidnet whoamiwhoami without a profile says You haven't logged in, run voidnet login first. and exits 1.
Where credentials live
| Source | Use |
|---|---|
--publisher-token flag | Single command override (highest priority) |
VOIDNET_PUBLISHER_TOKEN env | CI and scripts |
| OS keychain | Workstations (stored by login/configure) |
~/.config/voidnet/config.yaml | Fallback when no keychain exists |
Secrets are masked everywhere except the two once-only deliveries (key rotation, token creation). Never commit tokens; prefer keychain on workstations and short-lived tokens in CI.