132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# pdftract CLI Command Execution Documentation
|
|
|
|
**Bead ID:** bf-5kafx
|
|
**Date:** 2026-07-05
|
|
**Task:** Document command and execution results
|
|
|
|
## Commands Executed
|
|
|
|
### 1. Binary Location and Version
|
|
```bash
|
|
# Binary path
|
|
target/release/pdftract
|
|
|
|
# Version info (from doctor output)
|
|
pdftract version: 0.1.0 (git: f95f38009fe7a58d1a35127eadd...)
|
|
Binary size: 17.8 MB
|
|
```
|
|
|
|
### 2. Help Command
|
|
```bash
|
|
pdftract --help
|
|
```
|
|
**Exit Code:** 0 (success)
|
|
**Execution Time:** ~0.002 seconds
|
|
**Output Format:** Structured text with command listings and descriptions
|
|
**File Path:** `/home/coding/pdftract/target/release/pdftract`
|
|
|
|
### 3. Diagnostic Listing
|
|
```bash
|
|
pdftract list-diagnostics
|
|
```
|
|
**Exit Code:** 0 (success)
|
|
**Execution Time:** ~0.002 seconds
|
|
**Output Format:** Hierarchical diagnostic codes (100 codes)
|
|
- STRUCT_*: Structure-related diagnostics
|
|
- XREF_*: Cross-reference diagnostics
|
|
- STREAM_*: Stream diagnostics
|
|
|
|
### 4. Environment Health Check
|
|
```bash
|
|
pdftract doctor
|
|
```
|
|
**Exit Code:** 0 (success)
|
|
**Execution Time:** ~0.002 seconds
|
|
**Output Format:** Table format with status columns
|
|
|
|
### 5. Extraction Commands
|
|
|
|
#### Valid PDF (base_hello.pdf)
|
|
```bash
|
|
pdftract extract tests/document_model/fixtures/base_hello.pdf --json -
|
|
```
|
|
**Exit Code:** 0 (success)
|
|
**Execution Time:** 0.002 seconds
|
|
**Output Format:** Valid JSON to stdout
|
|
**File Paths:**
|
|
- Input: `tests/document_model/fixtures/base_hello.pdf`
|
|
- Output: stdout
|
|
|
|
#### Malformed PDF (js_in_openaction.pdf)
|
|
```bash
|
|
pdftract extract tests/document_model/fixtures/js_in_openaction.pdf --json -
|
|
```
|
|
**Exit Code:** 0 (ANOMALY - should be non-zero on error)
|
|
**Error:** "No /Root reference in trailer"
|
|
**Note:** This is expected behavior for this intentionally malformed test fixture
|
|
|
|
### 6. Validation Commands
|
|
```bash
|
|
pdftract validate <schema_file>
|
|
```
|
|
**Exit Code:** 1 (on validation errors)
|
|
**Execution Time:** ~0.004-0.013 seconds
|
|
**Output Format:** JSON path + error message
|
|
```
|
|
/ "schema_version" is a required property
|
|
/ "metadata" is a required property
|
|
```
|
|
|
|
### 7. Classify Command
|
|
```bash
|
|
pdftract classify <pdf_file>
|
|
```
|
|
**Exit Code:** 1 (when missing required features)
|
|
**Error:** Requires `--features profiles`
|
|
**Note:** Feature-gated command
|
|
|
|
## Exit Code Summary
|
|
|
|
| Exit Code | Meaning | Examples |
|
|
|-----------|---------|----------|
|
|
| 0 | Success | --help, list-diagnostics, doctor, successful extraction |
|
|
| 1 | Runtime Errors | Validation failures, missing features |
|
|
| 2 | Argument/File Errors | Invalid arguments, file not found, missing command |
|
|
|
|
## Performance Metrics
|
|
|
|
All commands executed in **excellent timing**:
|
|
- Help/diagnostics: ~0.002 seconds
|
|
- Doctor command: ~0.002 seconds
|
|
- Validation: ~0.004-0.013 seconds
|
|
- Extraction: ~0.002 seconds (valid PDFs)
|
|
|
|
**All commands < 30 seconds requirement** ✅
|
|
|
|
## Output Formats Observed
|
|
|
|
1. **Structured Text:** Help listings, diagnostic codes
|
|
2. **JSON Data:** Extraction output with schema_version 1.0
|
|
3. **Error Messages:** Path-based validation errors
|
|
4. **Tabular Data:** Doctor command health checks
|
|
|
|
## Warnings and Anomalies
|
|
|
|
1. **Exit Code Inconsistency:** Extract failures return exit code 0 (should return non-zero)
|
|
2. **Missing Version Flag:** Neither `--version` nor `-V` work correctly
|
|
3. **Feature Gating:** Some commands require specific build features
|
|
|
|
## File Paths Referenced
|
|
|
|
- Binary: `/home/coding/pdftract/target/release/pdftract`
|
|
- Test fixtures: `/home/coding/pdftract/tests/document_model/fixtures/`
|
|
- Valid PDF: `base_hello.pdf`
|
|
- Malformed test PDF: `js_in_openaction.pdf`
|
|
- Expected outputs: `*.expected.json` files in fixtures directory
|
|
|
|
## Environment Details
|
|
|
|
- **System:** Linux 6.12.63
|
|
- **Available RAM:** 59915 MiB
|
|
- **Binary location:** Also symlinked to `/home/coding/.local/bin/pdftract`
|
|
- **Cache status:** Directory does not exist (non-blocking)
|