Slicer Cli

slicer-cli — drive 3D Slicer over HTTP

slicer-cli is an agent-first wrapper around 3D Slicer's in-process HTTP server (default http://127.0.0.1:2016). This skill teaches you when to invoke it and how to do so safely.

> Tool: this skill drives the slicer-cli tool at > . Install it from there.

When to use

Invoke this skill when the user:

• Asks to interact with a running 3D Slicer instance, the MRML scene, or any Slicer node.
• Wants to load, list, inspect, export, or delete volumes inside Slicer.
• Asks to render a slice viewer or 3D view from a volume currently loaded in Slicer.
• Wants to query Slicer's DICOM database via DICOMweb (QIDO/WADO) or pull a study from Orthanc into Slicer.
• Asks to switch Slicer's GUI layout or grab a screenshot of the Slicer window.

Do NOT invoke this skill for:

• Parsing raw DICOM files outside of Slicer (use pydicom or similar).
• Writing image-segmentation algorithms (Slicer modules do this; the CLI does not).
• Launching the Slicer GUI itself (the user starts Slicer manually).
• DICOM DIMSE protocol work (C-STORE, C-FIND, C-MOVE) — that is a separate domain.

First contact (do this on every fresh task)

slicer-cli --json status

• On ok: true → proceed.
• On ok: false with code: E_NOT_RUNNING → stop. Tell the user Slicer

is not reachable. Do not fabricate Slicer state.

Optionally cache slicer-cli --json doctor once per session to know which capability probes (render, dicomweb, power-tool-endpoint, …) are green. Do not re-run status / doctor between every command.

Output contract — always pass --json

Every invocation should pass --json. Output is one JSON object per call.

Success envelope:

{"ok": true, "": "...", "": "..."}

Failure envelope:

{
  "ok": false,
  "error": {
    "code": "E_HTTP_5XX",
    "message": "...",
    "hint": "...",
    "endpoint": "/slicer/...",
    "http_status": 500
  }
}

Branch on error.code, never on error.message. Codes are stable public API; messages may be reworded between releases.

Exit code summary (full table → references/errors.md):

| Exit | Meaning | |---|---| | 0 | success | | 1 | bad CLI input (E_BAD_INPUT) | | 2 | Slicer-side HTTP error (E_HTTP_4XX/5XX, E_BAD_RESPONSE) | | 3 | network (E_NOT_RUNNING, E_NETWORK, E_TIMEOUT) | | 4 | config (E_CONFIG) | | 5 | exec disabled (E_EXEC_DISABLED) | | 6 | destructive guard fired (E_DESTRUCTIVE, E_EMPTY_SELECTOR) | | 7 | not yet implemented (E_NOT_IMPLEMENTED) |

Safety rules (non-negotiable)

1. Never run these without explicit user instruction:

• slicer-cli scene clear --confirm (wipes the entire MRML scene).
• slicer-cli system shutdown --confirm (kills the Slicer process).
• slicer-cli exec --code '…' / --file … (arbitrary Python in Slicer's process).

1. Hard-stop error codes — surface, do NOT retry, do NOT "fix" by adding flags:

• E_DESTRUCTIVE → the user did not authorize the destructive action. Surface it; ask the user.
• E_EMPTY_SELECTOR → an empty ` was passed. Don't substitute --all`. Ask.
• E_NOT_IMPLEMENTED → the feature lives in a later phase. The hint says which. Don't emulate via api raw or exec unless the user explicitly asks.
• E_EXEC_DISABLED → don't auto-pass --i-understand-the-risk. Ask.

1. Binary commands require --out: volume export, dicom instance,

render slice|threed|screenshot|gltf, and api raw … writing non-JSON. Pass --out - only when piping into another process. In --out - mode the success envelope routes to stderr; stdout is pure binary.

1. **Read references/safety.md before touching anything destructive or

before invoking exec.**

Common commands (the 80% surface)

| Command | One-line example | |---|---| | status | slicer-cli --json status | | doctor | slicer-cli --json doctor | | scene nodes [--class C] [--name N] | slicer-cli --json scene nodes --class vtkMRMLScalarVolumeNode | | scene ids | slicer-cli --json scene ids \| jq -r '.ids[]' | | node show | slicer-cli --json node show vtkMRMLScalarVolumeNode1 | | node delete | slicer-cli --json node delete vtkMRMLScalarVolumeNode2 | | volume list | slicer-cli --json volume list | | volume show | slicer-cli --json volume show vtkMRMLScalarVolumeNode1 | | volume export --out PATH | slicer-cli --json volume export vtkMRMLScalarVolumeNode1 --out /tmp/mr.nrrd | | volume import [--name N] | slicer-cli --json volume import /data/img.nrrd --name MyImg | | render slice [--orientation …] [--offset MM] --out PATH | slicer-cli --json render slice --orientation axial --offset 12 --out /tmp/ax.png | | render threed [--look A\|P\|L\|R\|I\|S] --out PATH | slicer-cli --json render threed --look A --out /tmp/3d.png | | dicom studies [--patient PID] | slicer-cli --json dicom studies --patient 12345 | | dicom series | slicer-cli --json dicom series 1.2.840… | | dicom instance --out PATH | slicer-cli --json dicom instance … --out /tmp/cxr.dcm | | sample load | slicer-cli --json sample load MRHead | | api routes [--method M] [--destructive] | offline route inventory | | api raw --out PATH | escape hatch for unwrapped endpoints |

For everything else (gui layout, markup *, exec, config get/show, system shutdown, full flag lists) → references/commands.md.

Worked examples

Example 1 — Render an axial slice from MRHead at offset 12 mm

# 1. Probe.
slicer-cli --json status

# 2. Find the MRHead volume id.
MR_ID=$(slicer-cli --json volume list \
  | jq -r '.volumes[] | select(.name == "MRHead") | .id')

# 3. Render.
slicer-cli --json render slice \
  --orientation axial --offset 12 --out /tmp/ax.png

render slice uses a named view (--view red/yellow/green, default red); --orientation and --offset set the slice plane within that view.

Example 2 — Export a volume to NRRD on disk

slicer-cli --json volume export vtkMRMLScalarVolumeNode1 \
  --out /tmp/mr.nrrd
file /tmp/mr.nrrd        # → "NRRD0004 ..."

--out is mandatory. Use --out - only when piping into another process; in that mode the success envelope ({"ok": true, "bytes": N, …}) routes to stderr.

Example 3 — DICOMweb QIDO (list studies for a patient)

slicer-cli --json dicom studies --patient 12345 \
  | jq '.studies[] | {patient_name, study_date, study_description}'

If the result is [], Slicer's DICOM database has no matching studies — dicom pull populates it from a remote DICOMweb peer. See references/dicomweb.md.

Example 4 — Cleanup pattern after sample load

When loading throwaway sample data and you need to clean up afterwards, capture node ids before AND after, then delete by id:

BEFORE=$(slicer-cli --json scene ids | jq -r '.ids[]' | sort)
slicer-cli --json sample load CTAAbdomenPanoramix
AFTER=$(slicer-cli --json scene ids | jq -r '.ids[]' | sort)

for id in $(comm -13 <(echo "$BEFORE") <(echo "$AFTER")); do
  slicer-cli --json node delete "$id"
done

Don't try to find new nodes by name — sample loads create multiple nodes with version-dependent names. Diffing ids is robust.

Example 5 — Capability check before render-heavy work

slicer-cli --json doctor | jq '.checks[] | select(.ok == false)'

• empty output → all probes green; proceed.
• name: "render" failing → render commands will fail with

E_BAD_RESPONSE and a hint mentioning GALLIUM_DRIVER=llvmpipe.

• name: "dicomweb" failing → /dicom/* endpoints unavailable.
• name: "power-tool-endpoint" failing → scene save, dicom pull,

markup line, and exec will 5xx.

If a probe is red, surface that to the user before falling back.

Discovery — learn the surface, don't guess

slicer-cli --json api routes                  # offline route inventory
slicer-cli --json api routes --destructive    # routes that need --confirm
slicer-cli --json api routes \
  | jq '.routes[] | select(.note != null)'    # routes with known caveats
slicer-cli --json doctor                      # live capability probe

api routes is offline — it works without Slicer running. Use it to pick the right command/endpoint for a task. The note field flags Slicer-side bugs and CLI workarounds (e.g., accessDICOMwebStudy is bypassed via /exec).

When to load a reference file

| Situation | File | |---|---| | Need a less-common command (gui layout, markup line, config, all flags) | references/commands.md | | Hit an unfamiliar error.code or want the full code ↔ exit map | references/errors.md | | About to do something destructive, or the user asked to use exec | references/safety.md | | Working with DICOMweb / Orthanc / dicom pull | references/dicomweb.md | | A command failed unexpectedly and the error doesn't tell you why | references/troubleshooting.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lightbridge-KS
• Source: Lightbridge-KS/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.