Error Handling

When a command fails, the CLI returns a non-zero exit code. If you’re using --json or --agent output mode, the envelope’s ok field is false and the summary field contains the error message.

Error envelope

{
  "ok": false,
  "data": null,
  "summary": "Not logged in. Run 'nexudus login' first.",
  "breadcrumbs": ["businesses", "list"]
}

Common errors

Error summary	Cause	Resolution
”Not logged in”	No stored credentials found	Run `nexudus login` to authenticate
”Unauthorized”	Invalid or expired credentials	Run `nexudus login` again with correct credentials
”Forbidden”	Your account lacks API permissions	Contact your Nexudus administrator to grant API access
”not found”	The entity ID does not exist	Double-check the ID — use `list` to find valid IDs
”Failed to create”	Validation error on create	Check required fields — run `nexudus <entity> create --help` for details
Non-zero exit code	General command failure	Read `stderr` or the JSON envelope for details

Checking for errors in scripts

When scripting, always check the exit code or parse the envelope:

# Check exit code
nexudus products get 12345678 --json
if [ $? -ne 0 ]; then
  echo "Command failed"
fi

# Parse the envelope with jq
result=$(nexudus products list --json)
ok=$(echo "$result" | jq -r '.ok')
if [ "$ok" != "true" ]; then
  echo "Error: $(echo "$result" | jq -r '.summary')"
fi

Diagnostics

If you’re unsure why commands are failing, run diagnostics:

nexudus doctor

This checks:

Whether credentials are stored and valid.
Whether the API is reachable.
Whether the CLI is up to date.