Voidnet CLI

The Voidnet CLI (voidnet) manages publisher apps from the terminal. It calls the same publisher API as the Console, using bearer-token auth instead of browser cookies.

npm i -g openvoidnet
voidnet login
voidnet apps list

Credentials

Voidnet uses three credential types:

Credential	Prefix	Held by	Used for	Accepted at
Buyer key	`vnb-sk-*`	Buyers and agents	Live tool and chat calls	`https://api.openvoidnet.com/v1-beta/*`
Per-app publisher key	`vnp-sk-*`	Your server config, one per app	The gateway presents it to your server so incoming calls are verifiable	Validated by your server; no Voidnet endpoint accepts it
Machine token	`vnp-pub-*`	Terminal, CI, scripts	Publisher management: list apps, read usage, rotate keys, refresh snapshots	`https://openvoidnet.com/api/publisher/v1/*`

Per-app keys travel gateway-to-server. Machine tokens travel client-to-Voidnet. They are not interchangeable.

Browser sign-in (recommended):

voidnet login

The CLI starts a one-shot listener on 127.0.0.1, opens Void Accounts in your browser, and waits up to 5 minutes. After approval, the token is stored at ~/.config/voidnet/cli.json (mode 600).

Approval happens on a consent screen showing the requesting client, the granted permissions in plain language, and an app picker: All apps (including apps created later) or Certain apps (selected checkboxes). The issued token carries read and verify permissions with a 30-day expiry. Publishing and key rotation require a token created in the Console.

To preselect apps:

voidnet login --app "$APP_ID_1" --app "$APP_ID_2"

The selection is recorded at approval time and enforced on every call. A token cannot exceed what was approved.

Token sign-in (headless and CI):

voidnet login --token vnp-pub-...

Create the token at Console → Machine Tokens. The full value is shown once at creation. Prefer piping the value over typing it.

Sign out:

voidnet logout

Revokes the token server-side and removes the local config.

Commands

voidnet apps list
voidnet apps list --format=json
voidnet logs tail --app "$APP_ID"
voidnet logs tail --app "$APP_ID" --request-id "$REQUEST_ID"
voidnet keys list "$APP_ID"
voidnet keys rotate "$APP_ID"

logs tail --request-id filters Usage Logs by request ID. The gateway forwards the same value as X-Voidnet-Request-Id on every routed call, so a publisher's own server logs join to console records on that value.

keys rotate revokes all keys for the app and prints the new full value once.

Scopes

Scope	Grants
`apps:read`	List apps and status
`apps:write`	Create drafts, edit descriptions
`apps:verify`	Verify servers, refresh snapshots
`apps:publish`	Publish to marketplace (console-issued tokens only)
`keys:read`	List key fingerprints
`keys:rotate`	Revoke app keys and issue a new one (console-issued tokens only)
`domains:write`, `domains:verify`	Domain verification lifecycle
`metering:read`	Usage logs with request IDs
`billing:read`	Payout visibility

Unknown scope strings are rejected. Calls outside a token's scopes fail with insufficient_scope; calls outside its bound apps fail with insufficient_binding.

Token rules

Full values appear once at creation. Lists show name, last 4 characters, scopes, bound apps, expiry, and last use.
Tokens support an app binding: all apps or a fixed list. A compromised token affects only its listed apps.
Suspended publishers lose machine access the same way they lose browser access.
Revoke unused tokens. last_used_at on each token shows whether it is active or dormant.

Troubleshooting

Symptom	Meaning
`Timed out waiting for browser approval`	No approval arrived in 5 minutes. Run `voidnet login` again.
`state mismatch (possible CSRF — aborted)`	The callback did not match this session. Never approve a login you did not start.
`Invalid grant: code already used`	Each code redeems once. Start a fresh `voidnet login`.
`no_publisher`	The signed-in account holds no active publisher. Complete publisher onboarding first.
`insufficient_scope`	The token lacks the operation scope. Browser logins grant read + verify; use a console-issued token for publish and rotate.

For AI coding agents

Agents driving this CLI (Claude Code, Cursor, Copilot, Opencode, or any other coding agent) need two things: the machine contract (see CLI Output Contract), and Voidnet platform knowledge. Both agent endpoints below are plain text over HTTPS — any LLM harness fetches them with a single GET, no special protocol needed. Fetch them instead of guessing:

Map first: https://docs.openvoidnet.com/llms.txt — every page with one-line scope notes. Cheap context; find the right page, then fetch it.
Full detail when needed: https://docs.openvoidnet.com/llms-full.txt — the complete documentation text. Ground truth for protocol versions, error catalogs, and billing rules.

Agent rules that hold for every run:

Run voidnet against production. Keep credentials in the environment or secret manager, never in files or chat.
Parse --json output, never tables. Never retry blindly on named errors.
Named errors are instructions: insufficient_scope means request a console-issued token, insufficient_binding means the token lacks that app, invalid_grant means start a fresh login. Never retry blindly.
Secrets appear once (rotate/create output). Store them in the environment or secret manager immediately; never echo them into logs, plans, or chat.
Destructive commands (keys rotate, publish flows) require explicit human approval in the task — an agent never runs them on inferred intent.

Updates and host discovery

The CLI checks /.well-known/voidnet.json on the management host at most once per day (cached in the OS config dir) and prints a one-line notice on stderr when a newer release exists. Unreachable metadata never fails a command. Versions below the published minimum fail loud with exit code 3 and the upgrade command. Disable with VOIDNET_NO_UPDATE_CHECK=1 or --no-update-check.

Voidnet CLI

On this page