Command-line interface¶

Reference for the ersilia command, generated from the source code. Run ersilia <command> --help for the same information in the terminal.

ersilia¶

Usage

ersilia [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

-v, --verbose¶: Show logging on terminal when running commands.

To learn more about a specific command, run: ersilia COMMAND –help

Each terminal has its own session. To share one across commands run through wrappers such as ‘conda run’, set ERSILIA_SESSION=<name>.

catalog¶

List models available locally or in the Ersilia Model Hub. By default shows locally fetched models in table format. Supports detailed metadata and individual model cards.

For a full list of models visit [bold cyan][link=https://catalog.ersilia.io/]https://catalog.ersilia.io/[/link][/bold cyan]

Usage

ersilia catalog [OPTIONS] [MODEL]

Options

--hub, --local¶: –hub lists models available in the Ersilia Model Hub; –local (default) lists locally fetched models.

-o, --output <output>¶: Save the catalog to a file. Accepted formats: .csv, .json.

--more, --less¶: –more shows additional model metadata; –less (default) shows only the EOS identifier.

--card¶: Display the full model card for a given model ID.

--task <task>¶

Filter models by task.

Options:: Annotation | Representation | Sampling

Arguments

MODEL¶: Optional argument

close¶

Stop the model served in this terminal and free its resources.

Usage

ersilia close [OPTIONS]

delete¶

Fully remove a model from the local computer. This includes the model files in the EOS directory, conda environment, Docker image and containers, pip package, and all associated database entries.

Usage

ersilia delete [OPTIONS] [MODEL]

Options

--all¶: Delete all locally available models.

Arguments

MODEL¶: Optional argument

example¶

Generate input examples for a model. A model must be served before running this command, or a model identifier must be provided. The number of examples and output file can be specified.

Usage

ersilia example [OPTIONS] [MODEL]

Options

-n, --n_samples <n_samples>¶: Number of examples to generate. Ignored in curated mode.

-o, --output_file <output_file>¶: Output file name.

-m, --mode <mode>¶

How examples are generated: random, curated, or deterministic.

Default:: 'random'
Options:: random | curated | deterministic

Arguments

MODEL¶: Optional argument

fetch¶

Download a model from the Ersilia Model Hub and set it up locally. By default, models are fetched from DockerHub. Use the –from_* flags to override the source.

Usage

ersilia fetch [OPTIONS] MODEL

Options

--from_dir <from_dir>¶: Fetch from a local directory containing the model repository.

--from_github¶: Fetch directly from the model’s GitHub repository.

--from_s3¶: Fetch from the Ersilia AWS S3 bucket.

--from_dockerhub¶: Fetch from DockerHub (the default when no other source is given).

--from_hosted <from_hosted>¶: Connect to a remotely hosted model service by providing its URL. Only creates a local folder structure; the model is not downloaded.

--version <version>¶: Specific Docker image version to fetch from DockerHub.

Arguments

MODEL¶: Required argument

info¶

Display information about the currently served model, including its title, description, identifiers, GitHub and S3 links, and Docker Hub details. A model must be served before running this command.

Usage

ersilia info [OPTIONS]

Options

-o, --output <output>¶: Save model information to a file. Accepted formats: .json, .csv.

run¶

Run predictions using the currently served model. Input must be a single-column CSV file. Output can be saved as .csv or .h5. A model must be served before running this command.

Usage

ersilia run [OPTIONS]

Options

-i, --input <input>¶: Required Path to a single-column CSV file containing the input data.

-o, --output <output>¶: Required Path to the output file. Accepted formats: .csv, .h5.

-b, --batch_size <batch_size>¶: Number of inputs processed per batch.

serve¶

Start a local API server for a previously fetched model. Once served, the model is ready to receive predictions via ersilia run. Optional flags configure session tracking, in-memory caching, and Isaura store access.

Usage

ersilia serve [OPTIONS] MODEL

Options

-p, --port <port>¶

Preferred port for the local API server.

Default:: 'auto-selected'

-t, --track¶

Track model runs (input/output stats, errors, timing, model metadata) by sending event data to Ersilia’s S3 tracking bucket.

Default:: 'off'

--enable_cache, --disable_cache¶

Enable a Redis in-memory cache for prediction results so repeat inputs return instantly.

Default:: False

-rs, --read_store¶

Read previously computed predictions from the Isaura store before running the model. Requires Isaura installed.

Default:: 'off'

-ws, --write_store¶

Write predictions to the Isaura store as they are computed. Requires Isaura installed and –access.

Default:: 'off'

-a, --access <access>¶

Visibility for predictions written to the Isaura store. One of: public, private. Required with –write_store.

Default:: 'unset'
Options:: public | private

--max_cache_memory_frac <max_memory>¶

Maximum fraction (0.0-1.0) of system RAM the Redis cache may use.

Default:: '0.3'

Arguments

MODEL¶: Required argument

test¶

Test a model and generate a detailed report on its expected behavior and performance. Supports surface, shallow, deep, and inspect check levels.

Usage

ersilia test [OPTIONS] MODEL

Options

--from_dir <from_dir>¶: Path to a local directory where the model is stored.

--from_github¶: Fetch the model directly from GitHub.

--from_dockerhub¶: Fetch the model from DockerHub.

--from_s3¶: Fetch the model from AWS S3 bucket.

--version <version>¶: Model version to fetch from DockerHub.

--shallow¶: Run shallow checks: model fetch, run, and output consistency.

--deep¶: Run deep checks: computational performance.

--surface¶: Run surface checks: simple model fetch and run.

--inspect¶: Run inspect checks: file structure and metadata.

--report_path <report_path>¶: Path to save the JSON report file.

--clean¶: Remove the temp folder after testing.

--permissive¶: Downgrade bash consistency check failures to warnings. Only valid with –from_dockerhub.

Arguments

MODEL¶: Required argument

uninstall¶

Fully uninstall Ersilia from this computer. Removes the Ersilia folder with all fetched models, all Ersilia Docker images and conda environments, and the ersilia Python package.

Usage

ersilia uninstall [OPTIONS]