Automation, headless CLI, and SDK roadmap

Equarith Headless is available for unattended searches, shell scripts, scheduled jobs, and local integrations. It runs the same EquarithEngine as the desktop application, keeps data and computation on the machine, and never opens an HTTP or TCP listener.

The command-line interface described on this page is available now. Official language SDK packages are not part of this release; their planned languages are listed under SDKs — coming soon.

Install and verify Equarith Headless

Standalone installers include the required Java runtime, so an end user needs neither a JDK nor the desktop application:

Windows x64: per-user MSI or EXE with managed PATH integration;
macOS x64 and ARM64: signed and notarized PKG installing /Applications/EquarithHeadless.app and /usr/local/bin/equarith-headless;
Linux glibc x64 and ARM64: DEB or RPM installing /usr/bin/equarith-headless.

After installation, open a new terminal and run:

equarith-headless version
equarith-headless --help
equarith-headless capabilities

version identifies the runtime and local protocol. capabilities is the authoritative machine-readable contract for the installed engine: it reports metrics, functions, search options, limits, export formats, and the effective parallelism configured for that command.

Developers building from source can use the shaded JAR instead:

./mvnw -pl equarith-cli -am package
java -jar equarith-cli/target/equarith-cli.jar --help

The development JAR requires JDK 25. Replace equarith-headless with java -jar equarith-cli/target/equarith-cli.jar in the examples below when using it.

Command reference

Options accept either --name=value or --name value. An option cannot be repeated. --threads must be a positive integer and defaults to the processors available to the process. Set it on the command; do not rely on constraints.cpuThreads to resize the integrated engine.

Show versions
```
equarith-headless version
```

Describe engine capabilities

equarith-headless capabilities [--threads=<n>]

Manage the shared license

equarith-headless license status [--threads=<n>]
equarith-headless license activate [--key-stdin] [--device-name=<name>] [--threads=<n>]
equarith-headless license refresh [--device-name=<name>] [--threads=<n>]
equarith-headless license deactivate [--threads=<n>]

Inspect an import

equarith-headless dataset inspect --data=<path> [--import=<json>] [--threads=<n>]

Validate a search request

equarith-headless validate --request=<json> [--resume-from=<checkpoint>] [--threads=<n>]

Run a blocking search

equarith-headless search --request=<json> --solutions=<jsonl>
    [--events=<jsonl|->] [--checkpoint-out=<file>]
    [--resume-from=<file>] [--threads=<n>]

Apply one saved solution to a compatible dataset

equarith-headless predict --data=<path> --solutions=<jsonl> --solution=<uuid>
    --output=<csv> [--import=<json>] [--label=<name>] [--threads=<n>]

Export saved solutions

equarith-headless export --solutions=<jsonl> --format=<format> --output=<path>
    [--ids=<uuid,uuid,...>]

Start the persistent local protocol

equarith-headless serve --stdio [--threads=<n>]

License and Demo limits

The headless runtime and desktop application share installation identity and license state when they run under the same system account and version. Check it with:

equarith-headless license status

license activate reads the key without echoing it when attached to an interactive terminal. No command-line option accepts the key itself. For automation, use --key-stdin and supply standard input from a secret manager or protected file descriptor so the key stays out of process arguments; do not put a literal key in a shell command, where the shell may record it in history. refresh renews an eligible certificate and deactivate releases the installation.

An unactivated Free/Demo search uses at most the first 200 source rows and four input variables. Academic and Pro licenses remove these two licensing limits, not the normal memory and engine safety bounds. Data and search computation remain local. Only an explicitly requested license operation contacts the licensing service.

End-to-end CLI tutorial

Create a job directory containing a numerical file such as measurements.csv and the following request.json:

{
  "schemaVersion": 1,
  "dataset": {
    "path": "measurements.csv"
  },
  "target": "y",
  "inputs": ["x1", "x2"],
  "metric": "rmse",
  "trainTest": {
    "mode": "FRACTION",
    "trainingFraction": 0.8,
    "sampleMethod": "RANDOM",
    "randomSeed": 42
  },
  "evaluateTestObjectivesDuringSearch": true,
  "constraints": {
    "maximumFormulaComplexity": 40,
    "randomSeed": 42,
    "candidateBudget": 100000,
    "timeLimitMillis": 60000
  },
  "searchOptions": {
    "population_size": 512,
    "evaluation_strategy": "auto",
    "constant_optimization_preset": "balanced"
  }
}

Relative dataset.path and resumeFrom paths are resolved from the directory containing request.json, so the job directory can be moved as a unit. A target or input may be referenced by an unambiguous column name or by the UUID returned by dataset inspect. If inputs is omitted, every column except the target is used.

1. Inspect the data

equarith-headless dataset inspect \
  --data=measurements.csv \
  --threads=8

The JSON result describes the detected dialect, import diagnostics, content fingerprint, row and column counts, and each column's UUID and statistics. Check that names, numbers, missing values, and the target column were interpreted as intended.

2. Validate the request

equarith-headless validate \
  --request=request.json \
  --threads=8

Validation loads the request and dataset, constructs the typed request, and applies the advertised engine-capability checks to the metric, split, selected functions, constraints, stop budget, and license limits. When loading and construction succeed, the command returns valid, issues, and a dataset description. A syntax, column, enum, I/O, or request-construction rejection can instead end with diagnostic stderr and the applicable non-zero exit code before that JSON body is produced. If --resume-from is supplied, the checkpoint is read with format and size safeguards; semantic checkpoint compatibility and some cross-field structural checks are applied only when search starts.

3. Run the search

equarith-headless search \
  --request=request.json \
  --solutions=solutions.jsonl \
  --events=events.jsonl \
  --checkpoint-out=latest.equarith-checkpoint \
  --threads=8

search blocks until completion, cancellation, or failure. The final Pareto front is written to solutions.jsonl, one versioned solution per line. A JSON summary is written to stdout. With --events=<file>, search-event envelopes are streamed to that JSON Lines file. Without it, a human-readable progress line is written to stderr about once per second.

Use --events=- when another program will consume event JSON Lines from stdout. In that mode, the short human summary moves to stderr so stdout remains machine-readable.

Pressing Ctrl+C requests cooperative cancellation first. If --checkpoint-out is present, the shutdown path attempts to preserve the latest checkpoint. Published solutions remain valid even if the most recent internal progress cannot be recovered.

Resume a compatible job with:

equarith-headless validate \
  --request=request.json \
  --resume-from=latest.equarith-checkpoint

equarith-headless search \
  --request=request.json \
  --resume-from=latest.equarith-checkpoint \
  --solutions=solutions.jsonl \
  --checkpoint-out=latest.equarith-checkpoint

--resume-from takes precedence over resumeFrom inside the request. Search resumes when engine, format, dataset, split, metric, functions and costs, constraints, and remaining budget are compatible. A semantic request mismatch or an already-exhausted smaller budget produces a warning and starts a fresh search. An unsupported engine or checkpoint format, or a malformed or invalid payload, fails explicitly.

4. Export the solutions

This command exports the complete loaded Pareto front as a Python module:

equarith-headless export \
  --solutions=solutions.jsonl \
  --format=python \
  --output=equarith_solutions.py

Use --ids=<uuid,uuid,...> to select specific solutions. Without it, every solution in the JSON Lines file is exported. Format identifiers are case-insensitive, and hyphens are converted to underscores:

CSV JSON PLAIN_TEXT LATEX
PYTHON R JULIA MATLAB OCTAVE SAS EXCEL WOLFRAM
C CPP FORTRAN JAVA KOTLIN SWIFT PHP CSHARP RUST GO
JAVASCRIPT TYPESCRIPT LUA VBA POSTGRESQL IEC_61131_ST

For example, --format=plain-text and --format=iec-61131-st are valid. CSV, JSON, plain text, and LaTeX are presentation or structured exports; the other targets generate executable source code or an Excel workbook. The JSON export is not the reloadable JSON Lines solution file used by predict and later export commands.

See Exporting data and formulas for target versions, generated helpers, numerical semantics, and deployment checks.

5. Predict with one solution

Copy the desired solution UUID from solutions.jsonl, then apply it to another compatible numerical file:

equarith-headless predict \
  --data=new-measurements.csv \
  --solutions=solutions.jsonl \
  --solution=<solution-uuid> \
  --output=predictions.csv \
  --label=prediction \
  --threads=8

The output CSV contains the imported columns followed by the prediction column. The new file must provide the column symbols used by the formula. A non-finite prediction is written as an empty prediction cell; the JSON command result reports validCount and invalidCount so automation can detect it.

Import overrides

Automatic import is the default. For a known dialect, create import.json:

{
  "delimiter": "SEMICOLON",
  "quoteCharacter": "\"",
  "headerMode": "PRESENT",
  "charsetName": "UTF-8",
  "decimalStyle": "COMMA",
  "missingValueTokens": ["", "NA", "NaN"],
  "trimWhitespace": true,
  "skipBlankRows": true,
  "maximumDiagnostics": 1000
}

Pass it to dataset inspect or predict with --import=import.json, or place the same object in dataset.import inside the search request. Supported delimiter values are AUTO, COMMA, SEMICOLON, TAB, and WHITESPACE; header modes are AUTO, PRESENT, and ABSENT; decimal styles are AUTO, DOT, and COMMA.

Search settings in request JSON

The most useful fields are:

metric: rmse by default; current IDs are rmse, mse, mae, nmse, sse, r_squared, squared_correlation, pearson, and hybrid.
trainTest.mode: NO_TEST, FRACTION, or FIXED_TRAINING_ROWS; use SEQUENTIAL or seeded RANDOM sampling as appropriate for the data.
constraints.candidateBudget and constraints.timeLimitMillis: bound the work; the search stops at the first applicable limit.
structural fields under constraints: maximum formula complexity, expression depth, variable occurrences, distinct variable count, and constant count.
constraints.normalizeDataset, constraints.forceAllInputVariables, and constraints.integerConstantsOnly: optional boolean restrictions.
constraints.randomSeed: controls search randomness; trainTest.randomSeed separately controls a random partition.
functionComplexities: sets per-function complexity costs. When a non-empty map is supplied, its keys also form the enabled function set.
searchOptions.population_size: 512 by default, currently from 64 through 8,192 in increments of 64.
searchOptions.evaluation_strategy: auto, full, or progressive.
searchOptions.constant_optimization_preset: fast, balanced, or accurate.
searchOptions.checkpoint_interval: five generations by default; zero disables periodic checkpoints, but a final checkpoint can still be created on normal completion, time limit, or cooperative stop.

The versioned request schema allows forward-compatible fields, but the integrated engine currently supports regression and built-in metrics and functions. Query capabilities instead of assuming that a future runtime has the same identifiers or bounds.

Files, limits, and reproducibility

Request and import JSON are limited to 16 MiB and reject duplicate keys.
Reloadable solution JSON Lines are limited to 64 MiB, 100,000 records, and four million characters per line.
A search owns at most 256 Pareto solutions in memory, with one best representative per complexity.
Rows with a non-finite target or selected input are excluded before the split.
The effective dataset, cell, column, and worker limits depend on the installed runtime and available memory; inspect capabilities for the current values.
Solution files, checkpoints, predictions, and completed exports are written to a neighboring temporary file, then replaced atomically when the filesystem supports it, with a regular replacement fallback. Event JSON Lines are streamed and therefore may end with the last completed record after interruption.
Preserve the request, input fingerprint, runtime version, seeds, worker count, solutions, and checkpoint when reproducibility matters. A different runtime, JDK, hardware environment, or worker count can change discovery order.

Exit codes

0: success.
1: unexpected or internal failure.
2: invalid command usage, option, parameter, or search validation.
3: file or input/output error.
4: search or prediction computation failure.
5: license operation failure.
130: interruption or cancelled search.

Write automation against these codes and machine-readable stdout. Human-readable stderr is diagnostic text, not a stable API.

Persistent local protocol

For several operations in one long-lived process, run:

equarith-headless serve --stdio --threads=8

The process exchanges one UTF-8 JSON-RPC 2.0 object per line over stdin and stdout. Stdout is reserved for protocol messages; diagnostics go to stderr. A client starts with:

{"jsonrpc":"2.0","id":1,"method":"system.handshake","params":{}}

The handshake reports protocol 1.3, runtime and engine versions, methods, export formats, and message and concurrency bounds. engine.capabilities reports the configured engine parallelism. system.describe returns the embedded OpenRPC description. The protocol covers license status, capabilities, local dataset loading, validation, search and checkpoints, solution storage and export, and chunked prediction.

One process accepts one active search. Start separate processes with explicit thread counts for concurrent jobs. The protocol has no port, remote authentication, network discovery, or remote computation.

SDKs — coming soon

Official SDKs are coming soon for Python, TypeScript, JavaScript on Node.js, Java, C#/.NET, C++, and Lua. They will control the locally installed Equarith Headless runtime without embedding or downloading another copy of the engine.

Until the packages and their publication metadata are released, use the CLI commands above or the local stdin/stdout JSON-RPC protocol. Do not treat an unreleased SDK source snapshot as a supported production package.

For license storage and the complete list of explicit network features, see Licensing, privacy, and network access. For formula interpretation and validation, see Understanding results and analysis.

Equarith 文档。