Exit codes

The walwarden CLI uses structured exit codes so scripts and CI pipelines can distinguish actionable failures.

Code	Name	Meaning
0	OK	Restore completed successfully. The completed state was reached and the audit chain was sealed.
1	RETRYABLE	A transient failure occurred. The restore job transitioned to failed_retryable. Common causes: network error during S3 download, transient S3 throttle. Retrying the restore (by issuing a new token) is reasonable.
2	USER_ERROR	Bad arguments or a rejected token. The CLI exited before creating a restore job. Common causes: missing --manifest, --target, or --mode; --confirm-destructive absent for in-place mode; WALWARDEN_TOKEN not set; token expired or already used; target database unreachable on pre-flight. Fix the input and reissue the token before retrying.
3	TERMINAL	A non-retryable failure. The restore job transitioned to failed_terminal. Common causes: manifest hash mismatch (the artifact may be corrupt), pg_restore exited with a non-zero code, malformed dump. Do not retry without investigating. Contact support with the restore job ID from the dashboard.
4	CANCELLED	The restore was interrupted by a signal. The CLI received SIGTERM or SIGINT (Ctrl-C), or the parent process was killed. The server watchdog will eventually transition the restore job to timed_out. Issue a new token and restart to complete the restore.

Using exit codes in scripts

WALWARDEN_TOKEN=<token> npx --yes walwarden-cli restore \
  --manifest <sha256> \
  --target '<dsn>' \
  --mode new_database
EXIT=$?

if [ $EXIT -eq 0 ]; then
  echo "Restore completed"
elif [ $EXIT -eq 1 ]; then
  echo "Transient failure — retry with a new token"
elif [ $EXIT -eq 2 ]; then
  echo "Bad input or expired token — check flags and reissue"
elif [ $EXIT -eq 3 ]; then
  echo "Terminal failure — do not retry without investigating"
elif [ $EXIT -eq 4 ]; then
  echo "Cancelled — restart when ready"
fi