The auth preflight

Credentials are resolved per run: an API key in OCTOLENS_API_KEY, or a profile stored by octolens login. The no-usable-credential family — MISSING_API_KEY, NOT_LOGGED_IN, NO_CREDENTIALS, NO_PROFILES — all exit 3: test MEMBERSHIP of the family (or exitCode === 3) to decide “do I need to authenticate?”, then read the specific member for the remedy. Which member a run gets depends on the command (whoami answers NOT_LOGGED_IN where a data command answers NO_CREDENTIALS for the identical state), so never branch on a single member. CONFLICTING_CREDENTIALS, INVALID_API_KEY, MISSING_PROFILE, NO_STORED_PROFILE, UNAUTHORIZED are deliberately NOT in the family — a credential exists and something else is wrong with it, so a login loop is the wrong recovery. The membership test, as a shell function:

needs_credentials() { [ "$1" -eq 3 ]; }   # test the family exit, never one member's code

octolens whoami --json
if needs_credentials $?; then
  octolens login   # get a credential, then re-run the original command
fi

Get started

Contract

Commands

Concepts

Guides

Scripting & agents

The auth preflight