Installation Install the Retto CLI using Cargo:
Building from Source Clone the repository and build:
git clone https://github.com/NekoImageLand/retto.git cd retto cargo build --release -p retto-cli
The binary will be available at target/release/retto-cli.
Feature Flags Enable optional features during installation:
HuggingFace Hub
CUDA Support
DirectML Support
cargo install retto-cli --features hf-hub
Command-Line Options The CLI accepts the following arguments:
retto-cli [OPTIONS] --images < PATH >
Model Paths --det-model-path
string
default: "ch_PP-OCRv4_det_infer.onnx"
Path to the text detection model
--cls-model-path
string
default: "ch_ppocr_mobile_v2.0_cls_infer.onnx"
Path to the text classification model
--rec-model-path
string
default: "ch_PP-OCRv4_rec_infer.onnx"
Path to the text recognition model
--rec-keys-path
string
default: "ppocr_keys_v1.txt"
Path to the character dictionary file
Path to an image file or directory. When a directory is provided, all image files will be processed recursively.
Device Selection Execution device for inference:
cpu - CPU-only executioncuda - NVIDIA GPU (requires backend-ort-cuda feature)directml - DirectML (Windows, requires backend-ort-directml feature) GPU device ID (for CUDA/DirectML backends)
HuggingFace Hub Automatically download models from HuggingFace Hub (requires hf-hub feature)
Basic Usage
Process a single image
retto-cli --images photo.jpg
Process a directory
The CLI will recursively find and process all image files: retto-cli --images ./screenshots/
View the results
Results are logged to the console. The CLI reports processing statistics: Found 42 files, processing... Successfully processed 42 images, avg time: 123.45ms
Examples Using Local Models Specify custom model paths:
retto-cli \ --det-model-path ./models/detection.onnx \ --cls-model-path ./models/classification.onnx \ --rec-model-path ./models/recognition.onnx \ --rec-keys-path ./models/dict.txt \ --images ./photos/
Using HuggingFace Hub With the hf-hub feature enabled, models are automatically downloaded:
retto-cli --use-hf-hub true --images ./documents/
On first run, models will be downloaded from the pk5ls20/PaddleModel repository on HuggingFace Hub and cached locally.
GPU Acceleration retto-cli --device cuda --device-id 0 --images ./images/
retto-cli --device directml --device-id 0 --images ./images/
Batch Processing Process multiple directories or use shell globbing:
# Process all images in multiple directories for dir in scans/ photos/ documents/ ; do retto-cli --images " $dir " done
Understanding the Output The CLI uses structured logging with debug information:
# Enable debug logging RUST_LOG = retto_core = debug, retto_cli = debug retto-cli --images test.png
Example output:
[2026-03-09T12:34:56Z DEBUG retto_core::session] Det result: DetProcessorResult { ... } [2026-03-09T12:34:56Z DEBUG retto_core::session] Cls result: ClsProcessorResult { ... } [2026-03-09T12:34:56Z DEBUG retto_core::session] Rec result: RecProcessorResult { ... } [2026-03-09T12:34:56Z INFO retto_cli] Successfully processed 1 images, avg time: 142.33ms
Implementation Details From main.rs:71, here’s how the CLI initializes the session:
let cfg : RettoSessionConfig < RettoOrtWorker > = RettoSessionConfig { worker_config : RettoOrtWorkerConfig { device , models }, .. Default :: default () }; let mut session = RettoSession :: new ( cfg ) ? ;
File discovery uses the walkdir crate (main.rs:72):
let walkers = WalkDir :: new ( & cli . images); let files = walkers . into_iter () . filter_map ( | e | e . ok ()) . filter ( | e | e . file_type () . is_file ()) . collect :: < Vec < _ >>();
The CLI currently logs results but doesn’t save them to files. For production use, consider piping the output or modifying the source to save JSON results.
Use GPU backends for large batch processingProcess directories instead of individual files to amortize initialization overheadEnable HuggingFace Hub to automatically use optimized modelsAdjust logging levels in production to reduce I/O overhead
Next Steps
Backends Learn about GPU acceleration options
Model Loading Understand model sources and configuration
