Skip to content

The neurodesk CLI

The neurodesk CLI (command-line interface) runs Neurodesktop’s helper tools. Run it in a JupyterLab or desktop terminal as your normal user:

Terminal window
neurodesk --help

To see the options of one command, add --help, for example neurodesk cite --help.

CommandWhat it does
neurodesk citeWrites a CITATIONS.md file for the Neurodesk tools you loaded. See Generate a citation list.
neurodesk kernelRegisters the Python inside a tool container as a Jupyter kernel.
neurodesk uvCreates a Python environment and kernel for one analysis folder. See Python environments with uv.
neurodesk jobsSends an analysis to a remote Slurm cluster (experimental). See Remote HPC jobs.

Use a tool container’s Python in a notebook

Section titled “Use a tool container’s Python in a notebook”

neurodesk kernel makes a notebook kernel that runs inside a Neurodesk tool container. Use it when a notebook needs the Python packages that ship with a tool, such as FSL’s Python:

Terminal window
neurodesk kernel add fsl/6.0.7.16 # or a tool name, for its default version
neurodesk kernel list
neurodesk kernel remove fsl/6.0.7.16

Refresh JupyterLab, then select the new kernel in the notebook’s kernel menu. To use another Python that the tool provides, add --python, for example neurodesk kernel add fsl --python fslpython.

CommandWhat it does
neurodesk updateUpdates the Neurodesk application menu to the latest tool list.
neurodesk checkChecks that CVMFS, the GPU, Slurm and T3 remote access work.
neurodesk infoShows the image version, CPU and memory limits, free storage, GPUs and the CVMFS server.
neurodesk testRuns the test suite that ships with the image.
neurodesk t3Sets up T3 Code remote access through Tailscale.

Run all checks:

Terminal window
neurodesk check

Each check prints PASS, FAIL or SKIP. A check is skipped when the feature is not in use, for example when there is no NVIDIA GPU. To run some of the checks, name them:

Terminal window
neurodesk check cvmfs
neurodesk check gpu slurm
CheckWhat it tests
cvmfsThe Neurodesk CVMFS repository is mounted and lists modules.
gpuAn NVIDIA GPU is visible. In a desktop terminal, it also tests OpenGL rendering.
slurmThe Slurm scheduler answers and lists its partitions.
t3T3 Code remote access is set up correctly.

The command exits with status 1 when a check fails. When you ask for help in the discussion forum, include the output of neurodesk info and neurodesk check.

neurodesk test runs the full test suite in /opt/tests. It takes some time, and some tests need network access, CVMFS or a running desktop. To run fewer tests, add pytest options:

Terminal window
neurodesk test -k cvmfs # only tests whose names contain "cvmfs"
neurodesk test -x # stop at the first failure

These commands are for AI coding agents that run analyses in Neurodesktop. The agent guidance in the image tells agents when to use them.

CommandWhat it does
neurodesk agent preflightShows the agent guidance revision, Lmod and the Slurm limits before an analysis.
neurodesk astraPublishes ASTRA analysis outputs (publish) and checks their recorded software versions (check).
neurodesk lightcone materializeRuns a Lightcone materialization on Slurm, outside sbatch.

Each command was a separate tool before the neurodesk CLI existed. The older names still work, so you do not need to change your scripts.

CommandOlder name
neurodesk citeneurodesk-cite
neurodesk kernelneurodesk-kernel
neurodesk uvneurodesk-uv
neurodesk jobsneurodesk-jobs
neurodesk updateneurodesk-update
neurodesk check gpuneurodesktop-gpu-check
neurodesk t3t3_neurodesk_setup
neurodesk agent preflightneurodesk-agent-preflight
neurodesk astraneurodesk-astra-provenance
neurodesk lightcone materializeneurodesk-lc-materialize