Skip to content

Narwhal CLI reference

narwhal-inference installs narwhal and the five narwhal-* commands.

  • Each executable accepts -h, --help, and --version.
  • Relative paths resolve from the process working directory.
  • python -m narwhal.cli starts a router.

Text-mode exit codes

narwhal config, narwhal dev, narwhal-engine, narwhal-attest, narwhal-serve, narwhal-profile, and narwhal-check use these codes in text mode:

Exit code Outcome
0 Success.
1 Operation failure: engine HTTP request, runtime inspection, listener bind, verification, or teardown.
2 Invalid arguments or configuration inputs.

These commands add exit codes for specific cases:

Command Exit code Case Reference
narwhal dev 1 The instance reports degraded. narwhal dev output and exit codes
narwhal dev setup, narwhal dev init 2 A download or an initialization check fails. narwhal dev output and exit codes
narwhal-engine prepare 2 Preparation fails. narwhal-engine actions
narwhal-engine 1 An output artifact already exists. narwhal-engine actions
narwhal-check 1 narwhal-check skips a gate with --evidence-out. narwhal-check exit codes
narwhal diagnostics collect 3 Partial bundle. narwhal diagnostics manifest and exit status
narwhal diagnostics collect 4 I/O failure. narwhal diagnostics manifest and exit status

Failure diagnostics

  • An expected failure writes one stderr line naming the command, operation, and affected path or value.
  • An unexpected failure prints a Python traceback.
  • Engine inspections keep subprocess output in the run's diagnostic logs.

JSON command results

narwhal config, narwhal diagnostics, narwhal dev, narwhal-engine, narwhal-profile, and narwhal-check accept --format json. With it, the command prints a versioned command result and sets its exit code from the result status.