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.clistarts a router.
-
Validate fleet files and inspect resolved defaults and paths offline.
-
Collect private router snapshots and incident artifacts.
-
Set up, launch, verify, exercise and stop a local development fleet.
-
Prepare and launch checked engine processes.
-
Serve engine identity and attestation data for one vLLM or SGLang engine.
-
Run a Narwhal router.
-
Measure engine behaviour and write the profile store.
-
Run deployment preflight gates.
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.