Exit Codes

The elven CLI uses categorized exit codes so shell wrappers and CI scripts can branch on the failure mode. These codes are stable across versions.

Code	Class	Meaning	Suggested handling
0	OK	Success.	Continue.
60	AUTH	Not signed in / token expired / token revoked / refresh failed.	Re-run elven login (or refresh the ELVEN_TOKEN).
70	API	Server returned 4xx/5xx with a body.	Inspect the JSON error; usually a validation or permissions issue.
80	USAGE	Bad input (missing required flag, malformed value).	Fix the call site.
90	NETWORK	Could not reach the server (DNS, offline, firewall).	Retry; check network.
1	UNKNOWN	Anything else.	Treat as a bug — file an issue at github.com/aoatkinson/elven-sdk.

Shell example

#!/usr/bin/env bash
elven listing mine --json > listings.json
case $? in
  0)  echo "ok" ;;
  60) echo "auth — re-login and retry" >&2; exit 1 ;;
  70) echo "api error — inspect listings.json for details" >&2; exit 1 ;;
  80) echo "bug in the wrapper — bad flag" >&2; exit 1 ;;
  90) echo "network — retrying"; sleep 5; elven listing mine --json > listings.json ;;
  *)  echo "unknown — investigate" >&2; exit 1 ;;
esac

In @elvenvtt/api

When using the typed library directly, catch by error class instead:

import { AuthError, ApiError, UsageError, NetworkError } from '@elvenvtt/api';

try {
  await elven.listings.create({ ... });
} catch (e) {
  if (e instanceof AuthError) return promptLogin();
  if (e instanceof UsageError) return console.error('bad input:', e.message);
  if (e instanceof ApiError && e.status === 422) return showValidationErrors(e.body);
  if (e instanceof NetworkError) return retry();
  throw e;
}

The class → exit code mapping is one-to-one — the CLI's fatal() helper classifies a thrown error and exits with the matching code.