Exit Codes

The nefia CLI uses structured exit codes to communicate the outcome of every operation. These codes are consistent across all commands and designed for reliable use in scripts and automation.

Exit Code Reference

When Each Code Occurs

Exit 0 -- Success

Returned when every targeted host completes the operation without error.

• nefia exec --target all -- hostname succeeds on all hosts.
• nefia fs read --host web-01 --path /etc/hostname reads the file successfully.
• nefia vpn status runs and displays the status table.

Exit 1 -- Partial Failure

Returned when at least one host succeeded and at least one failed, or when a diagnostic command detects failures. This is the most common non-zero code in multi-host operations.

• A command times out on one host but succeeds on the remaining four.
• One host has a broken SSH session while others respond normally.
• A file push succeeds on most targets but one host has insufficient disk space.
• nefia doctor detects one or more [FAIL] checks (warnings alone do not cause exit 1).

Exit 2 -- User Error

Returned when the CLI rejects the request due to a user-correctable problem.

• An unknown flag or missing required argument is provided.
• The configuration file is missing or contains invalid YAML.
• Authentication credentials are expired or missing (nefia login required).
• A policy rule blocks the requested command or path.

Exit 3 -- Internal Error

Returned when Nefia encounters an unexpected condition not caused by user input.

• A panic is caught by the top-level recovery handler.
• The VPN subsystem encounters an unrecoverable state.

Exit 130 -- Canceled

Returned when the user sends SIGINT (Ctrl+C). Nefia performs a graceful shutdown: in-flight commands are cancelled, connections are drained, and partial results are printed.

Error Codes

In addition to numeric exit codes, Nefia returns structured error codes in JSON output (--output json) and MCP responses. These error codes appear in the error_code field of per-host results.

Using Exit Codes in Scripts

Here is a pattern for handling each exit code in a bash script:

#!/bin/bash
nefia exec --target group:production --output json -- systemctl is-active app > result.json
rc=$?
 
case $rc in
  0)
    echo "All hosts healthy"
    ;;
  1)
    echo "Partial failure — check result.json for details"
    jq '.results[] | select(.exit_code != 0) | .host' result.json
    ;;
  2)
    echo "Configuration or auth error — fix and retry"
    exit 1
    ;;
  3)
    echo "Internal error — report bug with verbose output"
    exit 1
    ;;
  130)
    echo "Interrupted by user"
    exit 0
    ;;
esac

Machine-Parseable Output

Combine exit codes with --output json for full programmatic control:

// nefia exec --target all --output json -- df -h / (exit code 1)
{
  "exit_code": 1,
  "summary": "2/3 hosts succeeded",
  "results": [
    { "host": "web-01", "exit_code": 0, "stdout": "Filesystem  Size  Used ..." },
    { "host": "web-02", "exit_code": 0, "stdout": "Filesystem  Size  Used ..." },
    { "host": "db-01",  "exit_code": -1, "error": "connection timeout" }
  ]
}

Structured Error Codes

Nefia provides a structured error code system (E-codes) that maps each domain error to a detailed explanation with resolution steps. Use nefia explain <code> to look up any error code interactively.

nefia explain E2001
nefia explain --list

All domain errors are defined as sentinel errors that can be matched with Go's errors.Is(). When classifying errors from scripts or programs, use the error_code field (the string codes listed in the table above). Within Go code, type-safe matching via errors.Is(err, types.ErrXxx) is recommended.

Related