Command reference
Exit Codes
CLI exit code reference for scripting and CI integration
Every stax command exits with a numeric code indicating success or the category of failure. Use these codes in CI pipelines and scripts to handle different error conditions.
Reference
| Code | Meaning | Common causes |
|---|---|---|
| 0 | Success | Command completed without errors |
| 1 | Validation error | Missing required fields, invalid paths, bad frontmatter |
| 2 | Build error | Layer exceeds size limit, archive safety violation |
| 3 | Registry error | Authentication failure, network error, repository not found |
| 4 | Package resolution error | Dependency cycle, missing package, version conflict |
| 5 | Materialization compatibility error | No compatible adapter, lossy translation (when strict mode enabled) |
| 6 | Signature / verification error | Missing or invalid signatures, expired attestations |
Using exit codes in CI
# Fail the pipeline on any validation error
stax validate || exit 1
# Distinguish between build and registry errors
stax push ghcr.io/myorg/agent:latest
case $? in
0) echo "Pushed successfully" ;;
2) echo "Build error — check layer sizes" ;;
3) echo "Registry error — check authentication" ;;
*) echo "Unexpected error: $?" ;;
esacRelated
stax validate— Produces exit code 1 on validation failures- Troubleshooting — Detailed error messages and recovery steps