Exit Codes

The Arctic CLI uses exit codes to indicate the result of command execution.

Exit Code Reference

Code	Name	Description
0	Success	Command completed successfully
1	General Error	Unspecified error occurred
2	Usage Error	Invalid arguments or flags
3	Config Error	Missing or invalid configuration
4	Connection Error	Agent could not be reached
5	Auth Error	Invalid or expired credentials
6	Partial Failure	Some operations succeeded, others failed

Detailed Descriptions

0 - Success

The command completed without errors. For commands that return data, the output contains the requested information.

arctic peers list
echo $?  # Output: 0

1 - General Error

An unspecified error occurred during command execution. Check the error message for details.

arctic services create --target-peer nonexistent
# Error: peer not found
echo $?  # Output: 1

2 - Usage Error

The command was called with invalid arguments, unknown flags, or missing required parameters.

arctic services create
# Error: --target-peer is required
echo $?  # Output: 2

arctic peers list --unknown-flag
# Error: unknown flag: --unknown-flag
echo $?  # Output: 2

3 - Config Error

The CLI configuration is missing, invalid, or incomplete.

# When no config exists
arctic peers list
# Error: no current cluster set
echo $?  # Output: 3

4 - Connection Error

Could not establish a connection to the agent.

arctic health --url http://unreachable:8080
# Error: connection refused
echo $?  # Output: 4

5 - Auth Error

Authentication failed due to invalid or expired credentials.

arctic peers list --token "invalid_token"
# Error: unauthorized
echo $?  # Output: 5

6 - Partial Failure

Some operations succeeded while others failed. This exit code is primarily used by the cache refresh command when refreshing multiple clusters and some fail.

arctic cache refresh
# Cluster A: success
# Cluster B: connection refused
echo $?  # Output: 6

Using Exit Codes in Scripts

Check for Success

if arctic peers list > /dev/null 2>&1; then
    echo "Command succeeded"
else
    echo "Command failed"
fi

Handle Specific Codes

arctic health --url http://192.168.1.10:8080
exit_code=$?

case $exit_code in
    0)
        echo "Agent is healthy"
        ;;
    4)
        echo "Agent is unreachable"
        ;;
    5)
        echo "Authentication failed"
        ;;
    *)
        echo "Unexpected error: $exit_code"
        ;;
esac

Check Partial Failure

arctic cache refresh
exit_code=$?

if [ $exit_code -eq 0 ]; then
    echo "Cache refreshed successfully"
elif [ $exit_code -eq 6 ]; then
    echo "Some clusters failed to refresh"
elif [ $exit_code -eq 4 ]; then
    echo "All agents unreachable"
fi

Exit Codes and Output

Exit codes are independent of output format:

# Same exit code with different output formats
arctic peers list -o json
echo $?  # 0

arctic peers list -o yaml
echo $?  # 0

Error messages are always written to stderr, regardless of output format.

Exit Codes

On this page