SMILE CLI

Train, predict, serve, and script from the terminal

SMILE ships with a unified command-line launcher (smile on macOS/Linux, smile.bat on Windows) that exposes interactive REPLs, no-code model training, batch inference with SHAP explanations, online HTTP serving, and the autonomous Agent Hub runtime. Depending on the first argument you pass (or the absence of one), the launcher routes to:

Installation & Setup

Prerequisites

• Java 25 or later (the bundled JBR in the distribution is sufficient).
• Python 3 (optional — required only for the Studio notebook’s Python kernel and the ty language server).
• ARPACK / OpenBLAS (optional — for hardware-accelerated linear algebra).

First-Time Setup

Run the provided setup script once after unzipping the distribution. It installs optional native libraries (libarpack, libopenblas) via the system package manager and creates a Python virtual environment with the packages listed in conf/requirements.txt:

# macOS / Linux
path/to/smile/bin/setup

# Windows
path\to\smile\bin\setup.bat
    

Running the Launcher

# macOS / Linux
path/to/smile/bin/smile [command] [options]

# Windows
path\to\smile\bin\smile.bat [command] [options]
    

The launcher reads JVM options from conf/smile.ini before forwarding the remaining arguments to smile.Main. The system property smile.home points to the distribution root and is used by all launchers to locate resources such as bin/predef.jsh, bin/predef.sc, and serve/quarkus-run.jar. See JVM Tuning for how to add custom properties.

Java Shell (smile shell)

smile shell [jshell-options…]
    

Starts an interactive JShell session pre-configured for SMILE development:

1. The full SMILE classpath is added with --class-path.
2. JVM flags are injected into the remote JVM started by JShell: -XX:MaxMetaspaceSize=1024M, -Xss4M, -XX:MaxRAMPercentage=75, -XX:+UseZGC, --add-opens java.base/java.nio=ALL-UNNAMED, and --enable-native-access.
3. DEFAULT and PRINTING JShell startup scripts are loaded (making println() available without a class qualifier).
4. bin/predef.jsh is loaded, defining the compact color smile feedback mode, pre-importing every major SMILE package, and printing the SMILE banner.
5. Command history is persisted across sessions via java.util.prefs.Preferences.

Pre-Imported Packages

The following packages (along with static methods from java.lang.Math and smile.math.MathEx) are imported automatically by predef.jsh:

smile.util.*          smile.graph.*          smile.math.*
smile.stat.*          smile.data.*           smile.data.formula.*
smile.data.measure.*  smile.data.type.*      smile.data.vector.*
smile.io.*            smile.plot.swing.*     smile.interpolation.*
smile.validation.*    smile.classification.* smile.regression.*
smile.feature.*       smile.clustering.*     smile.hpo.*
smile.vq.*            smile.manifold.*       smile.sequence.*
smile.nlp.*           smile.wavelet.*        smile.tensor.*
smile.anomaly.*       smile.association.*
    

Any arguments after shell are forwarded directly to JShell. You can execute a script file non-interactively or save/restore interactive sessions:

# Execute a JShell script non-interactively
smile shell examples/toy.jsh

# Inside an interactive session: save and reload snippets
smile> /save session.jsh
smile> /open session.jsh
    

Scala REPL (smile scala)

smile scala [scalac-options…]
    

Starts a Scala 3 REPL pre-configured with -usejavacp and bin/predef.sc, which imports the top-level smile._ DSL, smile.io._, formula operators (e.g. "class" ~ "."), and high-level training helpers:

import smile._              // top-level Smile DSL
import smile.io._           // Read/Write helpers
import smile.data.formula._ // formula DSL
import smile.classification._
import smile.regression.{lm, ridge, lasso, gpr}
import smile.feature.*
import smile.clustering.*
    

Training Models (smile train)

smile train -d <file> -m <model> [global-options] <algorithm> [algo-options]
    

smile train trains a machine learning model (classification, regression, clustering, vector quantization, or anomaly detection) from a data file and serializes it to disk (.sml). It uses a two-level command structure: global options come first, followed by the algorithm sub-command and its options.

Global Options

Formula Auto-Detection

If --formula is omitted:

• Supervised learning (classification and regression): the response variable is chosen automatically by inspecting column names in priority order: class → target → y → the first column in the file.
• Unsupervised learning (clustering, vector quantization, and anomaly detection): all columns are included as features (~ .). If you supply a formula with a left-hand side (e.g. --formula "class ~ ."), the response column is excluded from the input feature schema.

Classification Algorithms

All classification sub-commands default to classification mode. Algorithms that also support regression expose --regression to switch modes.

Regression-Only Algorithms

In addition to passing --regression to random-forest, gradient-boost, cart, mlp, svm, or rbf, the following sub-commands are dedicated to regression:

Clustering, Vector Quantization & Anomaly Detection

Unsupervised sub-commands serialize a ClusteringModel, VectorQuantizerModel, or AnomalyModel:

Feature Transformation & Cross-Validation

Algorithms that sensitive to feature scale accept --transform <rule> to fit a smile.feature.transform pipeline alongside the model:

Pass -k <folds> (and optionally -r <rounds>) to evaluate with stratified cross-validation. By default, the saved model is retrained on the full training dataset; pass --ensemble (-e) to save the ensemble of fold models instead:

# 5-fold cross-validation, 3 repetitions, tagged with model ID and version
smile train -d data/weka/iris.arff -m iris_rf.sml \
  --model-id "iris-classifier-v1" --model-version "2.0.0" \
  -k 5 -r 3 --ensemble random-forest --trees 200
    

Batch Prediction (smile predict)

smile predict <data-file> --model <model-file> [options]
    

Loads a saved .sml model, scores every row in <data-file>, and writes one prediction per line to stdout.

Output Formats & SHAP Explanations

In plain-text mode, smile predict prints the predicted label (plus space-separated probabilities with -p), regression value, cluster ID + centroid, SOM grid cell + centroid + quantization error, or boolean anomaly flag + score. With --json or --explain, it emits one JSON object per line:

# Batch predict with posterior probabilities and local SHAP explanations
smile predict test.arff --model iris_rf.sml --probability --explain

# Example JSON Lines output across model types:
{"prediction":0,"probabilities":[0.982,0.018,0.000],"explanations":{"shap":[[0.142,-0.051,0.812,0.003],[...],[...]]}}
{"prediction":1,"centroid":[5.9016,2.7484,4.3935,1.4339]}
{"prediction":[0,2],"centroid":[5.0121,3.4210,1.4612,0.2415],"error":0.1423}
{"prediction":false,"score":0.3842}
    

All built-in classification and regression models support SHAP explanations (tree ensembles via exact TreeSHAP, linear models via exact linear attribution, and other models via KernelSHAP).

Online Serving (smile serve)

smile serve [model-options] [server-options] [llm-options]
    

Launches the Quarkus-based SMILE Serve HTTP inference server, combining three inference capabilities and a bundled React Web UI (/infer and /chat) in a single process:

• Classic ML (/api/v1/smile, /api/v1/ml/models) — serialized SMILE models (.sml)
• ONNX Runtime (/api/v1/onnx) — open neural network format (.onnx)
• LLM Chat (/api/v1/chat/completions, /api/v1/models) — OpenAI-compatible chat completions with continuous batching or ONNX Runtime GenAI

# 1. Serve a classic ML model on port 9090
smile serve --model iris_rf.sml --port 9090

# 2. Serve an LLM with ONNX Runtime GenAI
smile serve --llm microsoft/Phi-4-mini-instruct-onnx --port 8888

# 3. Serve a large language model with continuous batching & multi-GPU tensor parallelism
smile serve --llm Qwen/Qwen3.8-27B --devices 0,1 --tp-size 2 --max-batch-size 32

# 4. Query classic ML prediction
curl -X POST http://localhost:9090/api/v1/smile/iris_random_forest-1 \
     -H "Content-Type: application/json" \
     -d '{"sepallength":5.1,"sepalwidth":3.5,"petallength":1.4,"petalwidth":0.2}'
    

Agent Hub & Bot Service (smile hub)

smile hub [options]
    

Starts the always-on autonomous Agent Hub runtime backing Agent Studio. Agent Hub runs in the background (locally or on a server) to execute scheduled routines, ingest external events (timers, webhooks, emails, and calendar feeds), consolidate cross-project memory logs, stage outbound drafts for human approval, and publish live HTML Bot Pages.

Supported File Formats

smile train and smile predict use smile.io.Read.data(path, format) to load data. The format is auto-detected from the file extension (or defaults to CSV if the path has no extension); override it with --format.

Quoting --format and --formula on the Command Line

Because the launcher script and OS argument parser strip outer unescaped double quotes before forwarding arguments to smile.Main, escape inner double quotes when passing values containing =, spaces, or commas:

smile train -d data/iris.csv --format "\"header=true\"" --formula "species ~ ." -m iris_kmeans.sml kmeans -k 3
smile train -d data/prostate.csv --format "\"header=true,delimiter=\t\"" --formula "lpsa ~ ." -m prostate_ols.sml ols
    

smile train -d data/iris.csv --format "`"header=true`"" --formula "species ~ ." -m iris_kmeans.sml kmeans -k 3
smile train -d data/prostate.csv --format "`"header=true,delimiter=\t`"" --formula "lpsa ~ ." -m prostate_ols.sml ols
    

JVM Tuning (conf/smile.ini)

The file conf/smile.ini contains JVM flags passed to every smile invocation. Defaults are tuned for modern multi-core hardware (75% max RAM, ZGC, compact object headers, NUMA, and string deduplication):

# Heap: use up to 75% of RAM
-J-XX:MaxRAMPercentage=75
-J-XX:MaxMetaspaceSize=1024M
-J-Xss4M
-J-XX:+UseZGC
-J-XX:+UnlockExperimentalVMOptions -J-XX:+UseCompactObjectHeaders
-J-XX:+UseNUMA
-J-XX:+UseStringDeduplication

# System properties use the plain -Dname=value form (no -J prefix):
-Dsmile.agent.max-output-tokens=16384
    

Important: Always use the plain -Dname=value form (without a -J prefix) for system properties in conf/smile.ini so that both the Unix smile script and Windows smile.bat launcher forward the key-value pair intact.

Quick Reference Card

ROUTING
  smile                           → Agent Studio (GUI)
  smile shell  [args]             → JShell REPL
  smile scala  [args]             → Scala 3 REPL
  smile train  -d FILE -m MODEL <algo> [algo-opts]
  smile predict FILE -m MODEL [-p] [-e] [--json]
  smile serve  [-m MODEL] [--onnx-model O] [--llm CHAT] [--port P]
  smile hub    [--host H] [--port P] [--profile local|server]

CLASSIFICATION ALGORITHMS
  random-forest  gradient-boost  ada-boost  cart
  logistic  fisher  lda  qda  rda  mlp  svm  rbf

REGRESSION ALGORITHMS
  random-forest  gradient-boost  cart  mlp  svm  rbf
  ols  lasso  ridge  elastic-net  gaussian-process

CLUSTERING ALGORITHMS
  kmeans  xmeans  gmeans  deterministic-annealing (da)

VECTOR QUANTIZATION ALGORITHMS
  som  neural-gas  growing-neural-gas (gng)  neural-map  birch

ANOMALY DETECTION ALGORITHMS
  isolation-forest (iforest)  lof  ocsvm (one-class-svm)

CROSS-VALIDATION FLAGS (train)
  -k <fold>    k-fold CV
  -r <rounds>  repeated CV
  -e           save ensemble of fold models
  -s <seed>    fix RNG seed

FEATURE TRANSFORMS (--transform)
  standardizer  robust  winsor(lo,hi)  minmax  MaxAbs  L1  L2  Linf