Output

Every command takes --output (short form -o) with one of three values:

Any other value is refused with exit code 2.

Choose for peopleCopy Anchor Link

At a terminal, leave the default. If you pipe the output somewhere and still want the readable form, ask for it with -o text. Error messages are colored only when standard error is a terminal. Colored output of a successful -o text command follows no such check, so if you redirect it to a file, keep the escape codes out with --no-color, by setting NO_COLOR to any value, or with TERM=dumb.

Choose for scriptsCopy Anchor Link

Always pass -o json. With the default, the shape of a script's input would depend on whether a terminal happened to be attached, and failures would be printed as a sentence rather than as data.

nuvelics whoami -o json

A successful command prints one line on standard output:

{"meta":{"context":"prod","baseUrl":"https://api.nuvelics.com/api","orgId":"01K..."},
 "data":{"context":"prod","endpoint":"https://api.nuvelics.com/api","user":null,"organization":{"id":"01K..."}}}

(Abridged: a real response carries more fields in data and in meta.) The payload is always under data. For a single item that is the item itself, so a jq path looks like .data.id. For a list it is an object with items, pagination and, where the list can be filtered, filters, so use .data.items[]. See Filters and paging.

meta says what the command acted on. context and baseUrl are always set. orgId is set when the response itself names the organization, and is null otherwise, notably for every list and for commands that never reach the API. A null there is normal. The tool never makes an extra request to find the organization.

Commands that print plain textCopy Anchor Link

A few commands ignore -o json on success and print plain text instead of the envelope. These are the delete, revoke and remove commands (including story photos rm), the local context and config commands, and login and logout.

• The delete, revoke and remove commands, context add, context use, context remove, context copy-key, login and logout print a confirmation line, such as Datasource <id> deleted. Ignore it and rely on exit code 0.
• context list and config list print a plain list, and context current and config get print a bare value. A script can read these. config set prints nothing.

Failures of these commands are still reported as JSON under -o json.

FailuresCopy Anchor Link

Under -o json, a failure is one JSON object on standard error and standard output stays empty:

{"error":{"kind":"conflict","message":"...","exitCode":3,"retryable":true,"requestId":"...","fields":[]},
 "meta":{"context":"prod","baseUrl":"https://api.nuvelics.com/api","orgId":null}}

Under text and auto, a failure is a single human-readable line on standard error. Only -o json gives you the structured error, so pass it even on commands you expect to fail. What each kind means is on Exit codes and errors.

Text output keeps standard output cleanCopy Anchor Link

In text mode, a list prints its table on standard output, and the filters that were applied and the cursor to continue from go to standard error, so redirecting standard output captures only the table.

DiagnosticsCopy Anchor Link

Two flags help when something is wrong, and write to standard error: --trace prints each HTTP request and response, and --debug prints stack traces on errors. A trace hides credentials, but it shows request and response bodies as they are, so check it before you share it.