Nursim CLI

Command-line tool for generating Nursim clinical simulation challenges with AI.

Nursim is a platform for interactive nursing simulation challenges. This CLI helps educators turn a structured clinical case proposal into a ready-to-use challenge JSON: scenario, decision tree, questions, answer options, scores and formative feedback.

The tool is designed for nursing education workflows where generated content must remain grounded in a teacher-provided case brief, NANDA/NOC/NIC reasoning, the selected nursing model, the assessment framework and simulation best practices.

What You Can Do

• read: convert a teacher DOCX challenge proposal into a validated case-brief JSON.
• create: generate a Nursim challenge JSON from a case-brief JSON using an AI model.
• validate: validate a challenge JSON and fill an expert-review rubric document.
• publish: publish a validated challenge to Nursim.
• pipeline: run the authoring flow: read -> create -> validate. Publishing is run separately with publish.

Install

npm install -g @nursim/cli

Run the interactive CLI:

nursim

You can also run any command non-interactively by passing all required options.

Input DOCX Template

Start from the official teacher-facing case proposal template:

Download the Nursim clinical case brief template

The read command expects this structure. Teachers complete the DOCX; the CLI extracts and validates the machine-readable case brief before any model tokens are spent.

Configure AI Providers

The selected model is passed as:

provider:model-id

Examples:

openai:gpt-5.5
anthropic:claude-sonnet-4-6
google:gemini-2.5-pro
deterministic:valid

Set the API key for the provider you want to use:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Supported provider aliases:

| Provider | Model syntax | Required environment variable | | --- | --- | --- | | OpenAI | openai:<model> or gpt:<model> | OPENAI_API_KEY | | Anthropic Claude | anthropic:<model> or claude:<model> | ANTHROPIC_API_KEY | | Google Gemini | google:<model> or gemini:<model> | GEMINI_API_KEY | | Deterministic test provider | deterministic:valid | none |

The deterministic provider is local and useful for smoke tests. It does not call an external AI service.

Configure Nursim Publishing

Publishing needs the Nursim API base URL:

export NURSIM_URL="https://your-nursim-api.example.com"

You can also pass it per command:

nursim publish \
  --challenge challenge.json \
  --validation validation-report.json \
  --nursim-url https://your-nursim-api.example.com \
  --out runs

For normal use, do not pass --password. The CLI asks for it using a hidden prompt. Passing --password is intended only for controlled automation because shell history or process listings may expose command-line arguments.

Recommended Workflow

1. Read the teacher proposal

nursim read \
  --docx nursim_caso_insuficiencia_cardiaca.docx \
  --out runs

Output:

• case-brief.json: validated input for challenge generation.
• extraction.json: evidence of what was read from the DOCX.
• validation.json: schema validation result.

2. Create the challenge JSON

nursim create \
  --brief runs/read/<run-id>/case-brief.json \
  --model openai:gpt-5.5 \
  --language spanish \
  --out runs

Supported language values:

spanish, english, portuguese, galician, catalan, basque

Spanish aliases such as castellano, ingles, portugues, gallego, catala and euskera are also accepted.

Output:

• challenge.json: Nursim challenge creation payload.
• trace.json: model, settings, prompts, validation and repair evidence.
• metadata.json: reproducibility metadata.
• agents/: per-step generation artifacts.

3. Validate and fill the expert rubric

nursim validate \
  --challenge runs/create/<input-hash>/<run-id>/challenge.json \
  --out runs

Output:

• validation-report.json: publishability and validation findings.
• filled expert rubric DOCX.

The CLI includes an empty expert rubric template. Use --rubric only if you want to override it:

nursim validate \
  --challenge challenge.json \
  --rubric custom-expert-rubric.docx \
  --out runs

4. Publish to Nursim

nursim publish \
  --challenge challenge.json \
  --validation validation-report.json \
  --out runs

The CLI asks for:

• Nursim username
• Nursim password, hidden in the terminal

Publishing is blocked unless the validation report is publishable.

5. Run the full pipeline

nursim pipeline \
  --docx nursim_caso_insuficiencia_cardiaca.docx \
  --model openai:gpt-5.5 \
  --language spanish \
  --out runs

The pipeline currently runs read, create and validate in sequence. It does not publish to Nursim. If a step fails, the pipeline stops and writes the artifacts needed to inspect the failure. To publish a validated challenge, run nursim publish explicitly.

Interactive Mode

Run:

nursim

The CLI asks which action you want to run and then prompts for missing options:

1. Read challenge proposal
2. Create challenge JSON
3. Validate challenge and fill rubric
4. Publish validated challenge
5. Run read-create-validate pipeline

Interactive mode is the default when required parameters are missing and the terminal supports prompts. Passing all required flags makes the command suitable for scripts and reproducible research runs.

Command Reference

read

nursim read --docx <proposal.docx> --out <output-dir>

Optional:

--run-id <id>

create

nursim create \
  --brief <case-brief.json> \
  --model <provider:model-id> \
  --language <language> \
  --out <output-dir>

Optional:

--run-id <id>

validate

nursim validate --challenge <challenge.json> --out <output-dir>

Optional:

--rubric <expert-rubric-template.docx>
--run-id <id>

publish

nursim publish \
  --challenge <challenge.json> \
  --validation <validation-report.json> \
  --out <output-dir>

Optional:

--nursim-url <url>
--username <username>
--password <password>
--run-id <id>

Prefer the hidden password prompt over --password for normal use.

pipeline

nursim pipeline \
  --docx <proposal.docx> \
  --model <provider:model-id> \
  --language <language> \
  --out <output-dir>

Optional:

--nursim-url <url>
--username <username>
--password <password>
--rubric <expert-rubric-template.docx>
--run-id <id>

Example: OpenAI Generation

export OPENAI_API_KEY="sk-..."

nursim read \
  --docx nursim_caso_insuficiencia_cardiaca.docx \
  --out runs

nursim create \
  --brief runs/read/<run-id>/case-brief.json \
  --model openai:gpt-5.5 \
  --language spanish \
  --out runs

Example: Local Smoke Test

nursim create \
  --brief tests/fixtures/briefs/valid-hip-fracture.json \
  --model deterministic:valid \
  --language spanish \
  --out runs

This verifies the CLI flow without calling any external model provider.

Model and Prompt Behaviour

• Provider-specific settings are handled by the CLI. For example, if a model does not support a parameter such as temperature, the request is shaped so the unsupported setting is not sent.
• To change AI providers, pass a different provider:model-id value and set the matching API key environment variable.
• Generated artifacts include trace metadata for the selected model, settings, prompt version, policy version, schema versions, input identity and repair attempts. Keep those files with research runs so outputs can be audited later.
• Prompt and pedagogical-policy changes should be treated as versioned research changes because they can affect generated challenge quality and comparability.

Notes for Educators and Researchers

• The input case brief is validated before model generation.
• Generated challenge JSON is validated before saving or publishing.
• Invalid generated output can be repaired and revalidated before export.
• Every generation writes a trace package with prompts, model response metadata, model selection, settings, input identity and final artifacts.
• The generated challenge should still be reviewed by educators or experts before use with students.