CLI Usage

NIPACT commands keep project declarations separate from mutable runtime files. After nipact init, most commands can resolve the project root from --context when you run them from the workspace root that contains nipact.contexts.yaml.

nipact init

Initialize a packaged demo project and runtime root.

nipact init \
  --demo colors \
  --project-dir demos/colors/project \
  --runtime-dir demos/colors/runtime

Flags:

• --demo: packaged demo name. The current release supports colors, fmri, and dfc.
• --project-dir: directory where nipact.yaml, manifests, step YAML, and workflow YAML are written.
• --runtime-dir: directory where mutable runtime files are written.
• --context: optional context name. If omitted, NIPACT uses the demo name.

--project-dir and --runtime-dir must be empty and must not contain each other.

For each packaged demo, init writes project/sources.yaml and configures project/nipact.yaml with:

project/nipact.yaml excerpt

sources:
  index: sources.yaml

The source index maps named source bindings to registry/runtime-relative source paths. The colors demo uses a single global source binding:

project/sources.yaml

global:
  colors_source: data/color_source.json

The registry/runtime-relative path is data/color_source.json. Its resolved filesystem location is under the selected runtime root, such as demos/colors/runtime/data/color_source.json.

The fMRI and DFC demos use entity-specific source bindings and tiny generated .npy files under runtime_root/data/fmri/ or runtime_root/data/dfc/. Those demos are synthetic smoke fixtures for neuroimaging-shaped execution.

nipact init --demo fmri and --demo dfc create the packaged synthetic demos. The maintainer real-data fMRI and DFC tutorial workflows use separate post-init bootstrap scripts and private source data.

init writes or updates a workspace-local context index:

nipact.contexts.yaml

contexts:
  colors:
    project_dir: demos/colors/project

The index is only an alias table from context name to project root. Runtime paths, workflow files, step files, manifests, sources, and provenance remain defined by project/nipact.yaml, project/sources.yaml, and runtime/database/registry.db. Treat it as workspace-local state; decide in your own repository whether to ignore or track it.

For post-init commands, NIPACT resolves the project root in this order:

1. use --project-dir when provided
2. use nipact.contexts.yaml in the current directory
3. use the current directory when it contains nipact.yaml

If none of those are available, run from the workspace root, run from the project root, or pass --project-dir.

nipact validate

Validate a project context without mutating runtime files.

nipact validate --context colors

Flags:

• --context: context name expected in nipact.yaml.
• --project-dir: optional project directory containing nipact.yaml.

Validation reads nipact.yaml first. Initialized colors demo projects get the strict colors overlay for expected demo declarations, source data, manifests, registry rows, and hashes. Other prepared projects get generic structural validation: project/runtime config, manifest YAML, workflow YAML, step YAML, sources.index, sources.yaml shape and path safety, and source_inputs rules. Generic validation does not require runtime/database/registry.db when it is absent; when a registry exists, NIPACT runs a small registry preflight.

nipact validate checks listed source path syntax and containment, but it does not require every listed source file to exist. Selected run-plan construction and runtime execution check the source files requested by the jobs being run.

nipact workflow list

List workflows declared in the project context.

nipact workflow list --context colors

nipact workflow steps

List workflow steps that can be selected with --step.

nipact workflow steps \
  --context colors \
  --workflow base

The output is similar to:

step=color_local_transform output=local_color
step=color_candidate_select output=selected_color
step=color_cohort_fit output=cohort_fit
step=color_cohort_apply output=cohort_color
step=color_sector_analysis output=sector_counts
PASS: workflow steps

nipact workflow plan

Compile a selected workflow step into a read-only dependency plan.

nipact workflow plan \
  --context colors \
  --workflow base \
  --step color_sector_analysis

nipact workflow graph

Print graph JSON for a selected workflow step.

nipact workflow graph \
  --context colors \
  --workflow base \
  --step color_sector_analysis

The workflow graph JSON is a declaration-time topology artifact. String fields such as artifact_id or source_artifact_id identify workflow graph refs like artifact:<step>:<output>. They are not the integer registry artifact IDs used by nipact trace and the GUI.

nipact workflow run

Run a selected workflow step through Snakemake. In non-dry-run mode, NIPACT builds a run workspace, hydrates valid current published workflow outputs when they can satisfy upstream inputs, asks Snakemake to produce the remaining target file paths, publishes declared outputs from reachable non-reused jobs under the runtime root, and records current rows in runtime/database/registry.db.

The command prints a run summary and stage messages while Snakemake schedules and runs the DAG.

The run summary includes three planner fields:

• planned_jobs: jobs left in the generated Snakefile after reusable upstream producers are omitted.
• planned_reused_registered_artifacts: distinct prior registry artifacts selected as cache inputs.
• planned_hydrated_inputs: files the planner expects to copy into the current run workspace before Snakemake starts. Execution still revalidates those files before copying them.

Reuse is conservative. Same-workflow runs may hydrate valid current published outputs. Derivative workflows may reuse declared upstream outputs only through explicit base_workflow ancestry. Ambiguous or invalid reusable candidates fail closed instead of picking a file silently. The identity check compares callable references and parameters by their module:function string.

NIPACT does not record software-environment metadata, so it cannot auto-invalidate cached outputs after code, package, tool, or environment changes (see Scope and Limitations). Rerun the affected workflow targets after such changes.

Source-import steps resolve declared source_inputs from sources.yaml during run-plan construction. NIPACT passes the selected source files to Snakemake as rule inputs, checks that the requested source files exist, and records source artifact rows only for source files used by the compiled run plan.

nipact workflow run \
  --context colors \
  --workflow base \
  --step color_sector_analysis \
  --cores 1

Flags:

• --workflow: workflow name.
• --step: workflow step name. The step must be listed by nipact workflow steps.
• --cores: Snakemake cores. Default: 1.
• --dry-run: ask Snakemake to build the DAG without running jobs, publishing outputs, or updating runtime/database/registry.db. A dry run may still create the run workspace and hydrate planned reusable inputs so Snakemake can inspect the same concrete paths it would see in a real run.

There is no standalone nipact step run command. To run one step for testing, use nipact workflow run --workflow <name> --step <step> so the step is resolved in a workflow context.

nipact trace

Trace one registered artifact backward through its recorded dependencies. trace reads runtime/database/registry.db and does not execute workflows or mutate registry rows.

The workflow-coordinate selector resolves current published workflow outputs:

nipact trace \
  --context colors \
  --workflow base \
  --step color_sector_analysis \
  --output sector_counts \
  --address init

The output is similar to:

artifact_id=<id>
origin=workflow_output
is_published=true
workflow=base
step=color_sector_analysis
output=sector_counts
address=init
path=outputs/colors/base/color_sector_analysis/sector_counts/init.<output_hash>.json
content_digest=<digest>
output_hash=<output_hash>
parameter_hash=<parameter_hash>
upstream_artifacts=<count>
dependency_edges=<count>
manifest_bindings=<count>
provenance_status=complete
warnings=0
PASS: trace

To trace a source or intermediate artifact, use its registry artifact id or its registered runtime-relative path:

nipact trace \
  --context colors \
  --file-path data/color_source.json

Flags:

• --artifact-id: registry artifact primary key.
• --file-path: registered runtime-relative artifact path. It must begin with data/, runs/, or outputs/; any other prefix, absolute paths, paths containing .., and backslash-separated paths are rejected.
• --workflow, --step, --output, --address: workflow-coordinate selector for current published workflow outputs.
• --json: print the lineage graph JSON instead of the text summary.

Exactly one selector form must be provided: --artifact-id, --file-path, or the complete workflow-coordinate selector.

nipact gui

Serve the local read-only provenance GUI for one project context.

From the workspace root or project root, only --context is needed:

nipact gui --context colors

From another directory, pass the project root explicitly. Use an absolute path unless the relative path is from your current shell directory:

nipact gui \
  --context colors \
  --project-dir /path/to/workspace/demos/colors/project \
  --port 8765

Flags:

• --context: required context name expected in nipact.yaml.
• --project-dir: optional project directory containing nipact.yaml.
• --port: loopback port. Default: 8765.

The GUI resolves the runtime root from nipact.yaml, reads runtime/database/registry.db, and binds to 127.0.0.1. It shows the project summary, workflows, manifests, registered artifacts, artifact details, workflow topology, and artifact lineage topology. It is read-only.

Planned Commands

Workflow diff, manifest commands, step commands, broader report commands, docs export, entity-flow graphs, backend artifact search/pagination, real-data/BIDS demo bootstrap, and full neuroimaging tutorial workflows are planned future work. They should not be treated as runnable commands in the current release.