Skip to main content
The TalkValue CLI returns a predictable exit code on every run so shell scripts and CI pipelines can branch on outcome without parsing output. Pair the code with the JSON error envelope on stderr to surface a useful message.

​
Reference

CodeMeaningWhen you see it
0SuccessThe command completed and printed its result.
1General errorUnexpected failure. Network error or transient API issue.
2Usage errorBad arguments, unknown option, missing required value.
3Authentication errorNo credentials, invalid or expired token, organization access revoked.
4Not foundThe targeted resource (person, event, channel, company, tag) doesn’t exist.
5ForbiddenAuthenticated, but the active organization isn’t allowed to act on the resource.

​
Read the exit code

talkvalue path person get 999999
echo $?
# 4 = not found

​
Branch in a shell script

#!/usr/bin/env bash
set -e

if ! result=$(talkvalue path person get "$1" --json 2>&1); then
  case $? in
    3) echo "Authentication failed. Run 'talkvalue auth login'." >&2 ;;
    4) echo "Person $1 not found." >&2 ;;
    5) echo "Not allowed to read person $1 in this organization." >&2 ;;
    *) echo "Lookup failed: $result" >&2 ;;
  esac
  exit 1
fi

echo "$result" | jq '.data.email'
set -e halts on the first non-zero exit. The case block maps each domain code to a human-readable message and re-exits with 1 so the calling script can detect the failure.

​
Combine with the JSON error envelope

When --json is set (or output is piped), errors land on stderr as: 
{ "error": { "message": "Person 999999 not found" } }
Capture it separately from stdout to get both the message and the code: 
err=$(talkvalue path person get 999999 --json 2>&1 1>/dev/null)
code=$?
echo "exit=$code"
echo "$err" | jq -r '.error.message'

​
CI pipelines

Most CI runners (GitHub Actions, GitLab CI, CircleCI) fail a step on any non-zero exit code, so the CLI integrates without extra plumbing: 
- name: Export attendees nightly
  env:
    TALKVALUE_TOKEN: ${{ secrets.TALKVALUE_TOKEN }}
  run: |
    talkvalue path event person export 16 > attendees.csv
If auth login was skipped because TALKVALUE_TOKEN is missing, the command exits 3 and the CI step fails with the auth error printed to stderr.