pdftract/notes/bf-5kafx.md

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

# 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

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

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

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)

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)

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

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

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)