59 lines
2.1 KiB
Markdown
59 lines
2.1 KiB
Markdown
# pdftract CLI Exit Code and Output Format Verification
|
|
|
|
**Bead ID:** bf-698np
|
|
**Date:** 2026-07-05
|
|
**Command tested:** `target/release/pdftract` (17.8 MB binary)
|
|
|
|
## Exit Codes Discovered
|
|
|
|
### Exit Code 0 (Success)
|
|
- `pdftract --help` - Help display
|
|
- `pdftract list-diagnostics` - Diagnostic listing (100 codes)
|
|
- `pdftract doctor` - Environment health check
|
|
|
|
**ANOMALY:** Some error conditions return exit code 0:
|
|
- `pdftract extract --output /tmp/test_output <file>` returns 0 even when extraction fails
|
|
|
|
### Exit Code 1 (Runtime Errors)
|
|
- `pdftract validate` - JSON validation failures (missing required properties)
|
|
- `pdftract classify` - Missing feature errors (requires `--features profiles`)
|
|
|
|
### Exit Code 2 (Argument/File Errors)
|
|
- `pdftract --version` - Invalid argument
|
|
- `pdftract -V` - Invalid argument
|
|
- `pdftract` (no args) - Missing command
|
|
- `pdftract invalid-command` - Unrecognized subcommand
|
|
- `pdftract hash <file>` - File operation failures
|
|
|
|
## Output Format Analysis
|
|
|
|
### Text-Based Output
|
|
- **Help text:** Structured command listing with descriptions
|
|
- **Diagnostics:** Hierarchical categorization (STRUCT_*, XREF_*, STREAM_*, etc.)
|
|
- **Doctor:** Table format with status columns
|
|
|
|
### Validation Output
|
|
- **Error format:** JSON path + error message
|
|
```
|
|
/ "schema_version" is a required property
|
|
/ "metadata" is a required property
|
|
```
|
|
- **Quiet mode:** `--quiet` suppresses output, exit code only
|
|
|
|
### Key Observations
|
|
1. **No version flag available** - Neither `--version` nor `-V` work
|
|
2. **Fast execution** - Most commands complete in 0.002-0.004 seconds
|
|
3. **Exit code inconsistency** - Some errors return 0 (should return non-zero)
|
|
4. **Feature gating** - Some commands require specific build features
|
|
|
|
## Execution Timing
|
|
- Help commands: ~0.002 seconds
|
|
- Diagnostic listing: ~0.002 seconds
|
|
- Doctor command: ~0.002 seconds
|
|
- Validation: ~0.004-0.013 seconds
|
|
- All commands are very responsive (< 15ms)
|
|
|
|
## Recommendations
|
|
1. Add proper `--version` flag support
|
|
2. Fix exit code for extract failures (currently returns 0 on error)
|
|
3. Consider consistent exit code 1 for runtime errors vs 2 for argument errors
|