Biosimulant CLI

biosimulant is the canonical Biosimulant command line interface. It ships with the Desktop App and shares its data directory, runtime, labs, runs, and Hub credentials on a given machine.

Install

The CLI is bundled with the Desktop App. After installing the app from biosimulant.com/download, open Settings > CLI Tools > Install CLI to add the binary to your PATH.

The launcher lands at:

~/.local/bin/biosimulant

(Windows: %LOCALAPPDATA%\Programs\Biosimulant\bin\biosimulant.cmd.)

If the launcher directory is not on PATH, the CLI Tools card prints the shell snippet to add. See Desktop App for the full walkthrough.

Verify

biosimulant doctor

Auth

Login stores tokens locally so you do not repeatedly enter email and password:

biosimulant auth login

The CLI stores credentials in the OS keychain when available. If keychain storage is unavailable, it falls back to:

~/.config/biosimulant/credentials.json

The fallback file is written with owner-only permissions (0600) on Unix systems.

CI tokens

Automation can skip interactive login by setting environment variables. These values take precedence over stored keychain or file credentials:

export BIOSIMULANT_ACCESS_TOKEN=...
export BIOSIMULANT_REFRESH_TOKEN=...

For hosted CI, prefer a future scoped publish token or API key over full user credentials.

Status and logout

biosimulant auth status
biosimulant auth status --json
biosimulant auth logout

Output and exit behavior

• Every command accepts --json for machine-readable output.
• Successful commands exit with status 0.
• Validation, auth, network, and publish errors print to stderr and exit non-zero.

Run your first lab

Create a source-tree lab, add a model, validate it, then run or serve it:

biosimulant auth login
biosimulant labs init ./my-lab --name "My Lab"
biosimulant labs add-model ./my-lab ./models/growth --as growth
biosimulant labs validate ./my-lab
biosimulant labs serve ./my-lab
biosimulant labs run ./my-lab \
  --results-file results.json \
  --report-file run-report.html --open --json

labs serve opens a local browser UI for starting runs and inspecting run status, logs, results, and visuals. labs run is the headless equivalent for scripts.

Scripting and automation

Use biosimulant for repeatable workflows against your local state, runs, and Hub-backed metadata. The CLI is bundled with the Desktop App and shares its data directory.

Typical automation patterns

• Inspect the command catalog: biosimulant commands list --json
• Read local labs as JSON: biosimulant labs list --json
• Run exact desktop commands: biosimulant raw get_settings --json
• Chain scripts against local runs, labs, and Hub-backed metadata

Agent-friendly output

Every command supports --json, and long-running commands are designed for automation-aware output modes.

biosimulant auth status --json
biosimulant raw list_runs --input '{"status":"running"}' --json

Safe setup checks

Before running automation, verify the local runtime and PATH state:

biosimulant doctor
biosimulant runtime status --json

Example shell flow

RUN_ID=$(biosimulant runs list --json | jq -r '.data[0].id')
biosimulant runs results "$RUN_ID" --json

Pull and run a lab package

Use exact package refs in scripts when reproducibility matters. namespace/name resolves the latest accessible package, while namespace/name@semver pins an exact version.

LAB_REF="biosimulant/microbiology-hello-world-growth@1.0.0"
biosimulant labs run "$LAB_REF" \
  --results-file results.json \
  --report-file run-report.html \
  --open \
  --json

biosimulant labs run pulls or reuses the lab in the current directory, creates a local run, starts it, writes the run results payload to results.json, writes a static browser report to run-report.html, and opens that report. Pass --target ./labs to use a different destination parent. The CLI creates a named child folder unless the target itself is already a matching pulled project.

The CLI remains headless by default. Use --results-file for machine-readable JSON, --report-file for a browser artifact, and --open when you want the report launched. Add global --no-open to generate the report without opening a browser.

The expanded form is useful when you need to inspect or customize each step:

LAB_REF="biosimulant/microbiology-hello-world-growth@1.0.0"
LAB_ID="$(biosimulant labs pull "$LAB_REF" --json | jq -r '.data.local_id')"
RUN_ID="$(biosimulant runs create --lab-id "$LAB_ID" --json | jq -r '.data.id')"
biosimulant runs start "$RUN_ID" --report-file run-report.html --open --json
biosimulant runs results "$RUN_ID" --json > results.json

To reopen a report for a completed run later:

biosimulant runs open "$RUN_ID"
biosimulant runs open "$RUN_ID" --report-file run-report.html

Use --no-deps when you want to skip package-backed dependency hydration during lab pull. Use --force to refresh a matching pulled project from the package artifact.

Update

The CLI updates with the Desktop App. Use the desktop app’s update flow, then re-run Settings > CLI Tools > Install CLI to refresh the launcher with the bundled binary for the current Desktop build.

Package repository model

A package repository uses biosimulant-packages.yaml to declare many top-level packages in one repo release. A package entry can point at a lab directory or model directory. Nested labs and models stay embedded in the parent .bsilab unless they are explicitly declared as their own top-level package entries.

This is different from pip: one repo release can produce many Biosimulant artifacts, and a lab artifact can contain nested sublabs and models.

For the full publishing workflow, see Package & Publish.

Common command groups

biosimulant auth login
biosimulant auth status
biosimulant auth logout
 
biosimulant labs list
biosimulant labs init ./my-lab --name "My Lab"
biosimulant labs add-model ./my-lab ./models/growth --as growth
biosimulant labs validate ./my-lab
biosimulant labs serve ./my-lab
biosimulant labs run ./my-lab --json
biosimulant labs package ./my-lab --out dist
biosimulant labs search immune --json
biosimulant labs pull your-org/my-lab@1.0.0 --target ./my-lab
biosimulant labs publish ./my-lab --visibility private
biosimulant runs list --json
biosimulant runs remote create payload.json
biosimulant runtime status
 
biosimulant labs release validate biosimulant-packages.yaml
biosimulant labs release build biosimulant-packages.yaml --out dist/biosimulant-packages
biosimulant labs release publish biosimulant-packages.yaml
biosimulant labs release ci biosimulant-packages.yaml --publish

Related

• Command Reference: full raw command catalog.
• Desktop App: install the GUI workbench.
• Package & Publish: release workflow with biosimulant labs release.