CLI
CLI Output Contract
Machine guarantees for scripting the Voidnet CLI — streams, envelopes, exit codes, and prompt discipline.
This page is a contract between the CLI and anything that parses it: shell scripts, CI pipelines, and AI coding agents. Behavior here is asserted by tests; changes to it are breaking changes.
Streams
- stdout carries data only. Tables, JSON, IDs, rotated secrets. Everything on stdout is safe to pipe.
- stderr carries diagnostics and errors. Env identity, request lines, row counts, warnings, failures. Humans read it; scripts redirect it away.
--help,--version, and empty invocation print usage to stdout with no runtime chatter and exit 0.
JSON envelope
Every data command accepts --json and emits one object:
{
"data": {}
}One shape for every command, no metadata mixed into data. (apps list also accepts the legacy --format=json spelling; both produce the envelope.)
Exit codes
| Code | Meaning |
|---|---|
0 | Success. For status and doctor, every probe/check passed. |
1 | Usage error, auth failure, remote failure, environment failure, or any failed probe/check. stderr names the cause. |
3 | Reserved: client below minimum supported version (update checker). |
Prompt discipline
- The CLI never prompts without an interactive terminal. Piped and CI runs fail loud with a non-zero exit instead of hanging.
- The CLI never prints full secret values except the two once-only deliveries (
keys rotate, token creation), each labeled copy-once. - Errors are named shapes (
insufficient_scope,insufficient_binding,invalid_grant), never generic strings. Retry logic keys off codes: scope and binding failures never resolve by retrying; grant failures need a fresh login.
Modes
--json > --quiet > --verbose > default. --quiet shows errors only. --verbose restores request URLs, row counts, probe chatter, and the target line. Default prints clean tables; failures always name their target.