---
name: biosimulant-cli
title: Biosimulant CLI
description: Use the biosimulant CLI to create models, create labs, add models to labs, validate labs, run or serve simulations, inspect results, and publish to the Biosimulant Hub.
version: 2026.05.23
tags: [biosimulant, cli, labs, models, hub]
audience: Claude Code, Cursor, Continue, Aider
recommended: true
---

# Biosimulant CLI

Use this skill for terminal-first Biosimulant work: local models, source-tree labs, simulation runs, package artifacts,
and Hub publishing. The Desktop-bundled CLI and standalone CLI share the same canonical command implementation, local
state, runs, packages, and Hub credentials.

Biosimulant labs package scientific `BioModule` models with `lab.yaml` wiring, public inputs/outputs, runtime
configuration, visualisations, README evidence, and optional Hub publication metadata.

For publish-worthy scientific lab creation, also use:

- `biosimulant-lab-authoring.md` for clean `lab.yaml` / `model.yaml` structure and validation.
- `biosimulant-scientific-publishing.md` for source-faithful publishing quality gates.
- Runtime-specific skills such as `biosimulant-sbml.md`, `biosimulant-cellml.md`, or `biosimulant-onnx.md`.

## When To Use

Trigger this skill when the user asks to:

- create, import, inspect, export, publish, or pull a model
- initialize a lab, add a model to a lab, validate a lab, run a lab, or serve a lab UI
- inspect runs, logs, results, reports, jobs, runtime status, or local settings
- build, validate, publish, preview, import, or export `.bsimodel` / `.bsilab` packages
- authenticate the CLI or prepare CLI automation

If the user only wants the GUI Desktop app, point them to `https://biosimulant.com/download/desktop`. Otherwise prefer
CLI flows and use `--json` for agent-readable output.

## First Checks

```bash
biosimulant doctor
biosimulant commands list --json
```

Use the command catalog and `biosimulant <command> --help` as the source of truth for exact CLI coverage. Use
`--data-dir <DIR>` or `--profile <NAME>` when work must be isolated from the user's normal Desktop state.

## Auth

Authenticate before Hub operations:

```bash
biosimulant auth login
biosimulant auth status --json
biosimulant auth logout
```

Automation can pass credentials through environment variables:

```bash
export BIOSIMULANT_ACCESS_TOKEN=...
export BIOSIMULANT_REFRESH_TOKEN=...
```

## Primary Lab Workflow

Prefer the lab-centered commands for lab work:

```bash
biosimulant labs init ./my-lab --name "My Lab"
biosimulant labs add-model ./my-lab ./models/growth --as growth
biosimulant labs validate ./my-lab --strict
biosimulant labs serve ./my-lab --no-open --json-stream --port 0
biosimulant labs run ./my-lab --results-file results.json --report-file run-report.html --json --no-open
biosimulant labs publish ./my-lab --visibility private --json
```

Lab locators default to the current directory when it contains `lab.yaml`. Otherwise pass a local lab id, a lab path, or,
for `labs run` / `labs serve`, a lab package ref such as `namespace/name@1.0.0`. Omitting the version resolves the
latest accessible package.

`biosimulant labs serve [LAB]` starts a local browser UI for run creation, run status, logs, results, and visuals. It
opens by default; use `--no-open` to suppress opening. Use `--port 0` to avoid port conflicts in automation.

## Model Commands

```bash
biosimulant models create "Growth Model" python
biosimulant models import ./models/growth
biosimulant models list --json
biosimulant models get <model-id> --json
biosimulant models pull <namespace/name[@version]> --target ./models
biosimulant models export <model-id> ./dist
biosimulant models publish <model-id> --visibility private
```

When adding a model to a lab, prefer:

```bash
biosimulant labs add-model [LAB] <MODEL> --as <ALIAS>
```

`<MODEL>` can be a local model id, a model path, or an exact model package ref. The CLI vendors path/id models into the
lab under `owned/models/<alias>` and writes the lab manifest entry. Package refs are written as `package` plus exact
`version` and hydrated before validation/run when possible.

## Manifest Layout

Simple CLI-created labs may use:

```text
my-lab/
  lab.yaml
  owned/
    models/
  README.md
```

Curated publish-worthy labs should use the explicit source-tree layout documented in `biosimulant-lab-authoring.md`:

```text
labs/<lab-slug>/
  lab.yaml
  models/
    core/
      model.yaml
      src/
      data/
      tests/
    visualisation/
      model.yaml
      src/
      tests/
  assets/
  README.md
```

A model directory uses `model.yaml`; do not invent `biosim.yaml`.

Lab runtime uses `duration` for simulated time and `communication_step` for signal exchange boundaries. Set
`settle_steps: 1` when downstream visualisation modules need final producer outputs after the simulation duration:

```yaml
runtime:
  duration: 0.01
  communication_step: 0.01
  settle_steps: 1
  initial_inputs: {}
```

## Validation And Running

Validate before running or publishing:

```bash
biosimulant labs validate ./my-lab
biosimulant labs validate ./my-lab --strict
```

Run headlessly:

```bash
biosimulant labs run ./my-lab \
  --parameters-file params.json \
  --simulation-config-file sim.json \
  --results-file results.json \
  --report-file run-report.html \
  --json \
  --no-open
```

Inspect stored runs:

```bash
biosimulant runs list --json
biosimulant runs get <run-id> --json
biosimulant runs logs <run-id> --json
biosimulant runs results <run-id> --json
biosimulant runs open <run-id> --report-file run-report.html
```

Use lower-level `runs create` / `runs start` only when the user needs separate control over run lifecycle.

## Packages And Publishing

For a single lab, prefer:

```bash
biosimulant labs publish ./my-lab --visibility public --json
```

For repository-level releases with many package entries, use `biosimulant-packages.yaml`:

```bash
biosimulant packages validate biosimulant-packages.yaml
biosimulant packages build biosimulant-packages.yaml --out dist/biosimulant-packages
biosimulant packages publish biosimulant-packages.yaml
biosimulant packages ci biosimulant-packages.yaml --publish
```

For archive inspection and movement:

```bash
biosimulant packages preview ./dist/my-lab.bsilab
biosimulant packages import ./dist/my-model.bsimodel
biosimulant packages export-model <model-id> ./dist
biosimulant packages export-lab <lab-id> ./dist
```

## Public Hub Run Gate

Do not mark a public lab publish-complete after `labs publish` alone. A public lab is complete only when the Hub detail
endpoint reports a visible completed run:

```bash
biosimulant labs run /absolute/path/to/lab --json --no-open
biosimulant labs publish /absolute/path/to/lab --visibility public --json --no-open

hub_id=$(jq -r '.hub_id' /absolute/path/to/lab/.biosimulant-project.json)
biosimulant hub labs get "$hub_id" --json \
  | jq '.data | {is_public, completed_runs, run_count, package_name}'
```

Acceptance condition:

```text
is_public == true
completed_runs >= 1
```

`biosimulant hub labs list --json` is useful for catalog checks, but it is not sufficient for completed-run
verification because list responses may return `completed_runs: null`.

If the Hub detail endpoint has no completed run, create or reuse a completed local run and upload/sync it:

```bash
biosimulant runs upload <run-id> --json

local_id=$(jq -r '.local_id' /absolute/path/to/lab/.biosimulant-project.json)
biosimulant raw hub_sync_lab_runs --input "{\"lab_id\":\"$local_id\"}" --json
```

Then re-run `biosimulant hub labs get "$hub_id" --json`.

Hub upload requests can fail transiently with network errors. Retry failed publishes and re-check existing
`.biosimulant-project.json` metadata before changing a lab manifest.

## Runtime And Troubleshooting

```bash
biosimulant runtime status --json
biosimulant runtime prepare
biosimulant jobs list --json
biosimulant settings data-dir
```

If a command fails:

- Run `biosimulant doctor` first.
- Run `biosimulant auth status --json` before Hub commands.
- Re-run with `--json` for structured errors.
- Validate a lab with `biosimulant labs validate --strict` before publish.
- Inspect run state with `biosimulant runs get`, `runs logs`, and `runs results`.

## Safety Rules For Agents

- Do not write inside `~/.local/share/biosimulant/`; that is the install root.
- Prefer source-tree labs (`labs init`, `lab.yaml`) for user-editable work.
- Do not mutate unrelated local Desktop state unless the user asked for it; use `--data-dir` for isolated tests.
- Prefer exact command help and `biosimulant commands list --json` over remembered command names.
- Prefer `biosimulant labs ...` for lab UX.

## Pointers

- CLI overview: https://docs.biosimulant.com/references/cli/
- CLI command reference: https://docs.biosimulant.com/references/cli/command-reference
- Package workflow: https://docs.biosimulant.com/how-to/library/package-and-publish
- CLI download: https://biosimulant.com/download/cli
- Install script: https://biosimulant.com/install.sh