Nipoppy Cli

Skill: nipoppy-cli

Help users work with the nipoppy CLI for end-to-end neuroimaging dataset management, from raw DICOMs through BIDS conversion, pipeline execution, and IDP extraction.

Steps

1. Identify user context — determine which workflow stage the user is at:

• New dataset (no existing directory): direct to init
• Existing dataset: inspect for config.json and manifest.tsv to confirm it is initialized
• Command question: identify which command group applies from $ARGUMENTS or user message
• General workflow question: load ${CLAUDE_PLUGIN_ROOT}/references/workflow-overview.md

1. Load relevant reference — based on the identified context, read the appropriate file:

• Workflow overview / "what is nipoppy" / "full workflow": ${CLAUDE_PLUGIN_ROOT}/references/workflow-overview.md
• init or status: ${CLAUDE_PLUGIN_ROOT}/references/setup-commands.md
• track-curation or reorg: ${CLAUDE_PLUGIN_ROOT}/references/curation-commands.md
• bidsify: ${CLAUDE_PLUGIN_ROOT}/references/bids-commands.md
• process: ${CLAUDE_PLUGIN_ROOT}/references/process-command.md
• track-processing or extract: ${CLAUDE_PLUGIN_ROOT}/references/track-extract-commands.md
• pipeline search, pipeline install, or pipeline list: ${CLAUDE_PLUGIN_ROOT}/references/pipeline-catalog-commands.md
• pipeline create, pipeline validate, or pipeline upload: ${CLAUDE_PLUGIN_ROOT}/references/pipeline-authoring-commands.md
• When uncertain, load workflow-overview.md first, then the relevant group reference

1. Check dataset state — if a dataset path is provided or discoverable (cwd or $ARGUMENTS):

• Check for config.json (nipoppy dataset marker)
• Check for manifest.tsv (participant/session registry)
• Check the manifest.tsv for a ses column — its presence indicates a multi-session

dataset, which affects BIDS output paths

• Load ${CLAUDE_PLUGIN_ROOT}/references/setup-commands.md to determine the expected

sourcedata path for data readiness checks (do not hardcode the path)

• Report what is and is not present before giving command advice

4a. Error handling — if a pipeline command fails or the user reports an error:

• Direct the user to check logs under /logs///
• Report the relevant error lines from the log
• Re-runs can target specific subjects with --participant-id to avoid re-running

all subjects when only some failed

1. Provide targeted help — answer with:

• Full command syntax for the relevant subcommand(s)
• Applicable options from the reference, matched to what the user described
• Example invocations tailored to the user's dataset path and parameters when known
• Warnings for common pitfalls (missing manifest entries, uninitialized dataset, etc.)

1. Suggest next step — after answering, recommend the next logical nipoppy command

in the standard workflow order: init → track-curation → reorg → bidsify → process → track-processing → extract

Constraints

• Always verify config.json and manifest.tsv exist before recommending commands that require an initialized dataset (reorg, bidsify, process, track-processing, extract).
• Always warn that nipoppy pipeline commands (bidsify, process, extract) require Linux and Apptainer; they will not work on macOS or Windows.
• Never run nipoppy commands without --simulate or --dry-run unless the user explicitly confirms they want live execution. Note that --simulate and --dry-run availability varies by command — load the relevant reference to confirm which flag applies before suggesting it.
• Never add participants to manifest.tsv by hand — instruct the user to edit the file directly or use nipoppy's manifest update workflow.
• When explaining process or extract, always mention the --pipeline, --pipeline-version, and --pipeline-step options, as omitting them may apply the command to all configured pipelines unexpectedly.
• For HPC workflows, prefer --hpc slurm or --hpc sge when the cluster type is known

and supported — nipoppy generates and submits job scripts automatically. Use --write-subcohort only when the HPC scheduler is unsupported or manual job submission control is required; in that case, load ${CLAUDE_PLUGIN_ROOT}/references/process-command.md for the subcohort workflow.

• The nipoppy pipeline subgroup manages the pipeline catalog (install/search/upload); it does not run pipelines. Use process, bidsify, or extract to actually run pipelines.

Source & license

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

• Author: neuroanalytics
• Source: neuroanalytics/data-science-harness
• License: MIT

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