Exit codes

PreviewWindowsShips in the preview channel only. Not a stable release.

What the Harmony CLI returns, and how to branch on it in a script.

The CLI distinguishes failure kinds by exit code so a script can branch on them without parsing text. Text changes between releases; codes are the contract.

Observed codes

Verified against Harmony 3.24.1-preview.12:

Code	Meaning	Example
`0`	Success	`nala version`
`2`	Unknown command	`nala nonexistentcmd`
`10`	Validation failed — arguments did not match the command schema	`nala sessions` (missing subcommand), `nala tasks get <unknown-id>`

NOTE

This table lists codes confirmed by running the CLI, not the full set the implementation may define. Treat an unlisted non-zero code as a failure and read the accompanying error, which carries a machine-readable code of its own.

Error codes are separate from exit codes

A failure carries a named error code alongside the exit status:

Error [NALA_VALIDATION_FAILED]: Invalid arguments for command.
  remediation: The arguments did not match the command schema. (nala:validation)

Three parts worth using:

Part	Use
Exit code	Branch in a script
`NALA_*` code	Identify the specific failure
`remediation`	Show a human what to do

Transport failures are their own family

Codes prefixed DAEMON_ mean the CLI could not complete a conversation with the daemon, which is a different problem from a command being wrong:

Code	Means
`DAEMON_NOT_CONNECTED`	No daemon reachable
`DAEMON_TIMEOUT`	Daemon did not respond in time
`DAEMON_CANCELLED`	The call was cancelled
`DAEMON_RPC_ERROR`	The call failed at the daemon

Each carries a retryable flag. Retry transport failures; do not retry validation failures — a malformed command will be malformed the second time.

Scripting

nala tasks list
if ($LASTEXITCODE -ne 0) {
    Write-Error "nala tasks list failed with $LASTEXITCODE"
    exit $LASTEXITCODE
}

Bash:

if ! nala tasks list; then
  echo "nala tasks list failed with $?" >&2
  exit 1
fi

IMPORTANT

Do not treat a zero exit as evidence that work finished. nala tasks list succeeding means the listing succeeded, not that the tasks in it are done. Read task state — see delivery lifecycle.

Instance isolation shows up here

A CLI invocation reaches the daemon matching its own data suffix. If a script runs under a different suffix from the application, it will report transport failures against a daemon that is plainly running.

nala doctor --json

Compare the resolved data directory. See CLI configuration.