CLI Guide

Overview

The core mlia package provides the command-line interface. Installed plugins register the targets, backends, transformations, and post-analysis capabilities available through that interface.

This guide covers capability discovery, target-profile selection, analysis, and standardized output. Use the owning plugin documentation for target- or backend-specific options and result interpretation.

Main commands

The most important entry points are:

• Use mlia for model analysis and current workflows.
• Use mlia target for discovering target profiles.
• Use mlia backend for discovering, installing, and managing backends.

Together, these commands define the basic MLIA flow: discovery first, then analysis.

Optional terminal interface

With the optional mlia-tui package installed, mlia check --tui opens an interactive configuration session. Supplied check options prepopulate that session; a missing target or model can be completed there. Analysis starts only when the user selects Run. Without the package, requesting --tui reports how to install it. Ordinary commands remain available without the optional package.

--noninteractive still controls backend installation prompts; the TUI remains interactive. With --json, the latest completed result is emitted after the UI closes. A failed or cancelled latest attempt does not emit an earlier result.

A good starting sequence

If you are in a fresh environment, a practical first sequence is:

mlia --help
mlia target list
mlia backend list

That gives you a quick picture of what the environment can actually do before you start copying example commands from documentation.

Common workflows

Show top-level help:

mlia --help

List targets:

mlia target list

List backends:

mlia backend list

Run a compatibility check:

mlia check my_model.tflite --target-profile <target-profile> --compatibility

Run a performance check:

mlia check my_model.tflite --target-profile <target-profile> --performance

Request JSON output:

mlia check my_model.tflite --target-profile <target-profile> --performance --json

Every successful mlia check writes the canonical standardized output to mlia-output/mlia-output.json, or beneath the directory selected with --output-dir. The --json option additionally selects JSON instead of text for stdout; it does not control whether the canonical file is written.

Use measured profiling data alongside a source model:

mlia check my_model.tflite --target-profile <target-profile> --performance \
  --profiling-data <profiling-data-path> --json --out-dir <report-dir>

The model is optional when the profiling data can be analyzed independently:

mlia check --target-profile <target-profile> --performance \
  --profiling-data <profiling-data-path>

--profiling-data changes the source of the analysis facts; it does not start a separate reporting workflow. The selected target advisor still produces normal standardized output, which is rendered and passed to post-analysis plugins in the same way as model-only analysis.

--profiling-data is repeatable and MLIA preserves the supplied order. Core passes profiling inputs to the selected backend as a list even when only one path is supplied. Each path may be a file or directory; the selected backend defines which forms and contents it accepts. Backends advertise whether they can consume profiling data. Use --backend to select one explicitly. When it is omitted, MLIA selects the target's unique profiling-capable backend. MLIA reports an error if none is installed, if several require explicit selection, or if an estimator-only backend is requested.

Color output

MLIA enables colored CLI output when writing to an interactive terminal. The dark theme is used by default. To select a theme in the MLIA configuration file, set the top-level theme value:

theme = "light"  # or "dark"

You can override the configured theme for an invocation by setting either MLIA_LIGHT or MLIA_DARK to a non-empty value:

MLIA_LIGHT=1 mlia check my_model.tflite --target-profile <target-profile> --performance

The environment setting takes precedence over theme in the configuration file. Setting both MLIA_LIGHT and MLIA_DARK to non-empty values is an error; an empty value is ignored.

To disable colors explicitly for mlia, mlia target, and mlia backend, set the NO_COLOR environment variable to any non-empty value before running the command:

NO_COLOR=1 mlia check my_model.tflite --target-profile <target-profile> --performance

Color is also disabled automatically when standard output is not a TTY, such as when redirecting output to a file or piping it to another command.

Dynamic backend and analysis options

The check command can expose additional options from installed backend and post-analysis plugins. These options are registered before command-line parsing, so the available command surface depends on the current environment.

Use:

mlia check --help

to inspect the actual backend and post-analysis options available. Backend option values are passed to their owning backend. Analysis-plugin options decide whether the plugin runs after successful analysis.

The CLI first renders the processed standardized output and then invokes enabled post-analysis plugins with that same output, the execution context, resolved command parameters, and plugin-scoped configuration. These plugins extend what happens after analysis; they do not replace target collectors or analyzers.

Configuration

MLIA supports core, filtering, backend_options, and plugin-scoped settings in addition to the top-level color and theme settings. For example:

theme = "light"

[[filtering.collapse]]
kind = "code_stack"
attribute = "file"
globs = ["*/generated/*"]

[plugins.example]
output_format = "custom"

Collapse rules are applied during standardized-output post-processing. A plugin registered as example receives only the plugins.example table.

Plugin relationship

The core package provides commands, workflow orchestration, standardized-output processing, and rendering. Plugin packages can provide targets, backends, transformers, dynamic backend options, and post-analysis actions. The top-level command tree is core-owned.

A useful mental model is:

1. mlia is the front door.
2. mlia target and mlia backend expose installed capabilities.
3. Target and backend plugins determine how analysis runs.
4. Core validates, post-processes, and renders their standardized output.
5. Enabled analysis plugins consume the completed result.
6. Plugin docs explain the detailed behaviour owned by each plugin package.

Entity reasons in terminal output

The standardized entity table always displays Name, Kind, ID and Placement. Reason appears only when at least one displayed entity has a reported reason. Reason reads checks[].details.reasons from checks linked by entity_id. Each reason contains a description and a detail string, which may be empty. Multiple reasons are separated by semicolons, with duplicate text removed. When Reason is visible, empty or absent reasons display -. Long reasons wrap to the terminal width; full details remain in JSON. Placement alone does not imply a reason.

AI Tile, Ethos-U and Neural Technology all use this representation. No target identifiers or target-specific reason attributes are needed by the renderer. Whole-model checks and checks without an entity reference are not assigned to individual operators. Entity kind remains available in both JSON and the terminal table; Reason is an additional column.