CLI Workflows

This guide is for terminal users who want complete command-driven workflows.

PRISM is an add-on to BIDS, not a replacement.

1) Setup and Environment

Run setup once from repository root.

macOS/Linux:

bash setup.sh

Windows (PowerShell):

.\setup.ps1

Activate the project virtual environment before running commands.

macOS/Linux:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

Common issue:

  • Error: “You are not running inside the prism virtual environment”

  • Fix: Activate .venv and rerun the command.

2) Run PRISM Studio from Terminal

Purpose: launch the web interface while staying terminal-first.

python prism-studio.py

Expected result:

  • Local server starts.

  • UI opens at http://localhost:5001.

3) Validate a Dataset (CLI)

Purpose: validate PRISM extensions and optionally BIDS.

python prism-validator /path/to/dataset

Run PRISM + BIDS validation:

python prism-validator /path/to/dataset --bids

Write a machine-readable report:

python prism-validator /path/to/dataset --format sarif -o prism.sarif

Preview automatic fixes:

python prism-validator /path/to/dataset --fix --dry-run

Apply automatic fixes:

python prism-validator /path/to/dataset --fix

Common issue:

  • Error: path not found or empty dataset.

  • Fix: verify dataset root path and required BIDS files (dataset_description.json, subject folders).

4) Use prism_tools.py

Purpose: conversion, imports, scoring, and utility tasks.

Show available commands:

python prism_tools.py --help

Survey import from Excel codebook:

python prism_tools.py survey import-excel --excel surveys.xlsx --library-root library

Survey library validation:

python prism_tools.py survey validate --library library/survey

Survey conversion to PRISM dataset:

python prism_tools.py survey convert --input survey_export.xlsx --output /tmp/my_prism_dataset

Biometrics import from Excel codebook:

python prism_tools.py biometrics import-excel --excel biometrics_codebook.xlsx --sheet 0 --library-root library

Run scoring recipes:

python prism_tools.py recipes surveys --prism /path/to/dataset
python prism_tools.py recipes biometrics --prism /path/to/dataset

5) End-to-End Minimal Terminal Flow

source .venv/bin/activate
python prism-validator /path/to/dataset --bids
python prism_tools.py survey validate --library library/survey
python prism_tools.py recipes surveys --prism /path/to/dataset

Expected artifacts:

  • Validation report in terminal or output file.

  • Updated/fixed sidecars when --fix is used.

  • Derivative scoring outputs for recipe runs.

6) Daily Quality Commands

Fast smoke check:

bash scripts/ci/run_local_smoke.sh

Full runtime gate:

bash scripts/ci/run_runtime_gate.sh

Python tests:

pytest

Formatting and linting:

black .
flake8 .

7) Where to Go Next