Command Line Interface

KINTSUGI provides a command-line interface for common operations.

Commands

kintsugi check

Check all dependencies and report their status.

kintsugi check
kintsugi check --verbose  # More detailed output
kintsugi check --json     # Output as JSON

kintsugi info

Display system information and KINTSUGI version.

kintsugi info

kintsugi template

Generate a configuration template file.

kintsugi template -o config.json
kintsugi template --output my_config.json

kintsugi register

Run the registration workflow.

# Dry run (show what would be done)
kintsugi register config.json --dry-run

# Run registration
kintsugi register config.json

# Override config options
kintsugi register config.json --src /path/to/images --dst /path/to/output

kintsugi scan

Preview what kintsugi init will find in a directory.

kintsugi scan /path/to/directory

kintsugi init

Initialize a new KINTSUGI project with standard directory structure.

kintsugi init /path/to/project --name "My Project"
kintsugi init /path/to/project --name "My Project" --slurm  # Add SLURM support

# With microscope parameters
kintsugi init /path/to/project --name "My Project" \
    --tile-rows 9 --tile-cols 7 \
    --xy-pixel-size 377 --z-step-size 1500 \
    --numerical-aperture 0.75 --tissue-ri 1.44

Options:

--name: Project name (required)
--slurm: Add SLURM/Snakemake workflow support
--force: Refresh templates on existing project
--tile-rows, --tile-cols: Tile grid dimensions
--xy-pixel-size, --z-step-size: Pixel sizes in nm
--numerical-aperture, --tissue-ri: Optical parameters

kintsugi install

Install optional dependency groups.

kintsugi install gpu        # GPU acceleration (CuPy for CUDA)
kintsugi install torch      # PyTorch for deep learning models
kintsugi install bio        # Spatial biology analysis (scanpy, scimap, squidpy)
kintsugi install viz        # Napari visualization
kintsugi install claude     # Claude Code MCP integration
kintsugi install dev        # Development tools (pytest, ruff, black, mypy)
kintsugi install all        # All optional features

MCP Server Commands

KINTSUGI includes an MCP (Model Context Protocol) server for Claude Code integration.

kintsugi mcp start

Start the MCP server for Claude Code integration.

kintsugi mcp start

The server exposes image processing tools that Claude Code can use for signal isolation and quality assessment.

kintsugi mcp tools

List all available MCP tools.

kintsugi mcp tools

Available Tools:

Category	Tools
Signal Isolation	`load_channel`, `subtract_blank`, `denoise`, `denoise_advanced`, `apply_clahe`, `clean_background`, `gaussian_subtract`
Quality Assessment	`assess_quality`, `compute_snr`
Visualization	`get_image_stats`, `get_thumbnail`
Workflow	`list_channels`, `save_processed`, `suggest_parameters`, `generate_jupyter_cell`
Parameter Learning	`get_learned_parameters`, `record_successful_parameters`, `suggest_with_learning`, `approve_and_learn`, `get_learning_statistics`

kintsugi mcp config

Generate and create Claude Code MCP configuration for a project.

kintsugi mcp config /path/to/project

This automatically creates .claude/settings.local.json with the MCP server configuration. If the file already exists, it adds the KINTSUGI server to your existing configuration.

Use --print-only to display the configuration without creating files:

kintsugi mcp config /path/to/project --print-only

Configuration File Format

The configuration file is a JSON file with the following structure:

{
    "src_dir": "/path/to/source/images",
    "dst_dir": "/path/to/output",
    "reference_image": "cycle1.tif",
    "image_type": "tif",
    "series": 0,
    "max_image_dim_px": 2048,
    "max_processed_image_dim_px": 2048,
    "micro_rigid_registrar_cls": "RigidRegistrar",
    "align_to_reference": true,
    "create_masks": true,
    "resolution_xyu": [0.325, 0.325, "um"],
    "channel_names": [],
    "compose_non_rigid": true,
    "crop_to_overlap": true
}

Workflow Commands (HPC/Snakemake)

Manage the Snakemake-based processing pipeline for SLURM clusters.

kintsugi workflow config

Generate Snakemake workflow configuration. Auto-detects SLURM accounts, calculates GPU and CPU slots, reads microscope parameters from meta/experiment.json.

kintsugi workflow config /path/to/project
kintsugi workflow config /path/to/project --print-only  # Preview without writing

kintsugi workflow check

Show live per-account resource availability (GPU and CPU slots).

kintsugi workflow check /path/to/project

kintsugi workflow run

Run the Snakemake processing pipeline. Auto-calculates concurrent job count from live resource availability.

kintsugi workflow run /path/to/project              # Full pipeline
kintsugi workflow run /path/to/project --dry-run     # Preview
kintsugi workflow run /path/to/project --cycles 1-3  # Specific cycles
kintsugi workflow run /path/to/project --forcerun stitch  # Force re-run
kintsugi workflow run /path/to/project --local --cores 4  # Local execution
kintsugi workflow run /path/to/project -j 16         # Override job count

SLURM Commands

Manage legacy SLURM job submission.

kintsugi slurm init

Add SLURM support to an existing project.

kintsugi slurm init /path/to/project

kintsugi slurm submit

Submit processing jobs to SLURM.

kintsugi slurm submit /path/to/project
kintsugi slurm submit /path/to/project --steps decon,edf
kintsugi slurm submit /path/to/project --cycles 1-5
kintsugi slurm submit /path/to/project --dry-run

kintsugi slurm status

Check SLURM job status for a project.

kintsugi slurm status /path/to/project

kintsugi slurm cancel

Cancel all KINTSUGI SLURM jobs for a project.

kintsugi slurm cancel /path/to/project

Environment Variables

Variable	Description
`KINTSUGI_DATA_DIR`	Default data directory
`KINTSUGI_DEVICE_MODE`	Processing backend: `gpu` or `cpu` (set by Snakemake)
`VIPS_PATH`	libvips binary directory (Windows)
`SLURM_ACCOUNT`	Default SLURM account (auto-detected)
`SLURM_JOB_ACCOUNT`	Current job’s SLURM account (set by SLURM)