CLI: Command-Line Interface¶

Traitly includes a command-line interface that allows running analyses directly from the terminal, without writing Python code. It is especially useful for processing batches of images on servers or computing environments where notebooks or interactive scripts are not available.

Basic usage¶

traitly fruit_internal -i PATH [-o PATH] [--json PATH] [--num_cores N]
traitly fruit_external -i PATH [-o PATH] [--json PATH] [--num_cores N]
traitly info # Print package, system, and dependencies metadata

The input (-i) can be a single image or a folder with multiple images.

A JSON file is required to configure the analysis

All analysis configuration must be passed through a .json file with --json.

There are two ways to obtain one:

Option 1 – From Python:

Adjust the parameters on a representative image
Save the configuration with analyzer.save_parameters()
Pass the generated .json file with --json in the terminal

Option 2 – From a template:

Copy the base file, modify the parameters you need in any text editor, and save it as .json. Then pass it with --json.

View JSON template

To learn what each parameter does, see the documentation for FruitInternalAnalyzer or FruitExternalAnalyzer.

Arguments¶

Argument	Type	Default	Description
`fruit_internal`	`flag`	—	Runs internal structure analysis (`FruitInternalAnalyzer`)
`fruit_external`	`flag`	—	Runs external appearance analysis (`FruitExternalAnalyzer`)
`info`	`flag`	—	Print traitly and system metadata
`-i`, `--input`	`str`	—	Path to the image file or folder to analyze (required)
`-o`, `--output`	`str`	`None`	Output directory; if `None`, a `Results/` subfolder is created inside the input folder
`--json`	`str`	`None`	Path to the `.json` parameters file generated by `save_parameters()`
`--num_cores`	`int`	`1`	Number of CPU cores for parallel processing
`--no_morphology`	`flag`	—	Skips morphology analysis
`--no_color`	`flag`	—	Skips color analysis
`--help`	`flag`	—	Displays available arguments and usage examples

Important

fruit_internal and fruit_external are mutually exclusive, and only one can be used per call.

Examples¶

Print available arguments:

# General arguments:
traitly --help

# Method-specific arguments:
traitly fruit_internal --help
traitly fruit_external --help

Internal analysis on a folder, using saved parameters in a JSON file:

traitly fruit_internal -i data/fruit_slices/ --json config.json

External analysis with custom output and parallel processing:

traitly fruit_external -i data/whole_fruits/ -o results/ --num_cores 4

Analysis on a single image:

traitly fruit_internal -i data/image_001.jpg --json config.json

Morphology only, skip color:

traitly fruit_internal -i data/slices/ --json config.json --no_color

Check installed version:

traitly info

Outputs¶

The CLI generates the same files as analyze_folder() from Python:

File	Description
`morphology_results.csv`	Morphological metrics for all detected fruits
`color_results.csv`	Color metrics for all detected fruits
`session_report.txt`	Session summary: images processed, fruits detected, processing times, and parameters used
`error_report.txt`	Per-image error detail (only generated if any image failed)
Annotated images	One annotated image per processed image

All files are saved to the directory specified with -o, or to a Results/ subfolder inside the input folder if not specified.

Shiny App¶

Requires the app dependencies to be previously installed. See the Installation section for details.

To launch the Traitly interactive app from the terminal, run:

traitly-app

Once started, a URL will appear in the terminal similar to:

http://127.0.0.1:8000

Copy and paste it into your browser to open the app.

Optionally, you can specify the host and port:

traitly-app --host 127.0.0.1 --port 8000