Exit Codes

Uni-CLI uses exit codes from sysexits.h — the UNIX standard for machine-parseable process exit status. Every exit code tells an AI agent exactly what kind of failure occurred and what to do next.

Code Reference

Code	Constant	Meaning	Agent Response
0	SUCCESS	Command succeeded	Use the data from stdout
1	GENERIC_ERROR	Unclassified error	Read stderr JSON for details
2	USAGE_ERROR	Bad arguments or syntax	Fix the command invocation
66	EMPTY_RESULT	No data returned	Try different parameters or query
69	SERVICE_UNAVAILABLE	Target site is down	Retry later
75	TEMP_FAILURE	Temporary failure	Retry with exponential backoff
77	AUTH_REQUIRED	Authentication or permission needed	Run unicli auth setup SITE or inspect policy
78	CONFIG_ERROR	Adapter misconfigured	Read and fix the YAML adapter

Code 0 — Success

The command completed and produced output. Data is on stdout in the selected envelope format.

unicli hackernews top
echo $?    # 0

Code 1 — Generic Error

An error that does not fit other categories. Check stderr for a structured error envelope:

unicli example broken 2>/tmp/err.json
echo $?    # 1
cat /tmp/err.json

{
  "error": "unexpected_response",
  "adapter_path": "/path/to/adapter.yml",
  "step": 0,
  "action": "fetch",
  "message": "Expected JSON, got HTML"
}

Code 2 — Usage Error

The command was invoked incorrectly — missing required arguments, unknown flags, or invalid syntax.

unicli hackernews
# Error: missing command. Available: top, new, ask, show, jobs, ...
echo $?    # 2

Agent action: fix the command syntax. Run unicli list SITE to see available commands and arguments.

Code 66 — Empty Result

The command executed successfully against the API, but the result set is empty. This is not an error — the query simply matched nothing.

unicli reddit search --subreddit "tinysub" --query "xyzzy"
echo $?    # 66

Agent action: try broader search terms, different parameters, or a different time range. The adapter and API are working correctly.

Code 69 — Service Unavailable

The target service is unreachable. The site may be down, blocked, or experiencing an outage.

unicli example fetch-data
echo $?    # 69

Agent action: retry after a delay. If the failure persists, check if the site is globally down or if the network is restricted.

Code 75 — Temporary Failure

A transient error — rate limiting, temporary server error, or network glitch. The built-in retry mechanism has already attempted retries and exhausted them.

unicli twitter timeline
echo $?    # 75

Agent action: wait and retry the entire command. Consider adding a rate_limit step to the adapter if rate limiting is the recurring cause.

Code 77 — Auth Or Permission Required

The command needs authentication or was stopped by local permission policy. Authentication failures usually need fresh cookies. Permission failures usually name the matching deny rule in the error envelope.

unicli bilibili feed
echo $?    # 77

Agent action:

unicli auth setup bilibili    # Interactive: opens Chrome login
unicli auth check bilibili    # Verify cookies are valid
unicli bilibili feed          # Retry

For permission_denied, inspect error.suggestion and the local ~/.unicli/permission-rules.json file.

Code 78 — Config Error

The adapter YAML is invalid or misconfigured. This typically means a selector changed, a URL is wrong, or the pipeline has a structural error.

unicli example broken-adapter
echo $?    # 78

Agent action: read the adapter YAML at the path in the stderr error JSON, fix the configuration, and retry. See the Self-Repair guide for the full workflow.

Programmatic Handling

Shell Script

unicli bilibili feed --json
case $? in
  0)  echo "Success" ;;
  66) echo "No results" ;;
  77) unicli auth setup bilibili ;;
  75) sleep 10 && unicli bilibili feed --json ;;
  *)  echo "Unexpected error" ;;
esac

AI Agent (pseudocode)

result = run("unicli bilibili feed --json")

if result.exit_code == 0:
    return parse_json(result.stdout)

if result.exit_code == 77:
    run("unicli auth setup bilibili")
    return retry()

if result.exit_code == 78:
    error = parse_json(result.stderr)
    adapter = read_file(error.adapter_path)
    fix = apply_suggestion(adapter, error.suggestion)
    write_file(error.adapter_path, fix)
    return retry()

if result.exit_code in [69, 75]:
    wait(exponential_backoff)
    return retry()

Source Definition

Exit codes are defined in src/types.ts:

export const ExitCode = {
  SUCCESS: 0,
  GENERIC_ERROR: 1,
  USAGE_ERROR: 2,
  EMPTY_RESULT: 66,
  SERVICE_UNAVAILABLE: 69,
  TEMP_FAILURE: 75,
  AUTH_REQUIRED: 77,
  CONFIG_ERROR: 78,
} as const;

These values follow the BSD sysexits.h convention, ensuring compatibility with UNIX toolchains and CI/CD systems that interpret exit codes programmatically.