Exit codes

Generated from the code

The table is printed by the binary itself via make gen, so it cannot drift from the codes the program actually returns.

The table

Code	Meaning
0	Everything went fine.
1	Something went wrong and hostsctl has no more specific code for it.
2	The command line itself was wrong; emitted by clap, never by hostsctl.
3	The config is missing, unreadable, invalid, or holds errors that check reports.
4	The target file or the backup directory is not writable — retry under sudo.
5	Reading or writing a file failed for a reason other than permissions.
6	A remote blocklist could not be downloaded.

Using them

The distinction that matters in automation is 3 from 4: a broken config needs a human, a permission failure needs sudo. Both check and apply return 3 when the config has errors, so the same branch covers a linting run and a real write.

#!/usr/bin/env bash
set -uo pipefail

hostsctl check
case $? in
  0) ;;
  3) echo "config is broken, not retrying" >&2; exit 1 ;;
  *) echo "unexpected failure" >&2; exit 1 ;;
esac

sudo hostsctl apply -y

check exits 0 when it found only warnings — a warning is something worth reading, not something worth stopping a pipeline for.

Output streams

Error messages go to stderr and normal output to stdout, so hostsctl list | head works the way you expect — including the SIGPIPE behaviour of an ordinary unix tool, which Rust otherwise suppresses.