# CLI Usage Guide

`spMetaTME` is designed around a powerful Command Line Interface (CLI) that simplifies common tasks like metabolic inference and model pretraining. This guide explains how to use these commands.

## Getting Help

The `spmetatme` command provides help information for all its subcommands.

```bash
spmetatme --help
```

For help on a specific subcommand, use:

```bash
spmetatme infer --help
spmetatme pretrain --help
```

---

## 1. Metabolic Inference (`spmetatme infer`)

Predict metabolic reaction fluxes and identify spatial domains. This is the main tool used for analyzing new datasets.

### Basic Usage
```bash
spmetatme infer --input data/my_sample.h5ad --model-species human --metabolic-model breast_cancer
```

### Key Parameters
| Parameter | Short | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `--input` | `-i` | Yes | - | Path to input `.h5ad` file. |
| `--metabolic-model` | - | Yes | - | Name of the metabolic model (e.g., `breast_cancer`, `human_gem`). |
| `--model-species` | `-s` | No | `human` | Species context for the pretrained model (`human` or `mouse`). |
| `--preprocess / --no-preprocess` | - | No | `True` | Whether to run MAGIC preprocessing. |
| `--finetune / --no-finetune` | - | No | `False` | Whether to finetune the model on your input data first. |
| `--epochs` | - | No | `10` | Number of finetuning epochs. |
| `--num-clusters` | - | No | `7` | Number of clusters for spatial domain identification. (Alias: `--n-clusters`) |
| `--method` | - | No | `kmeans` | Clustering method (options: `mclust`, `leiden`, `louvain`, `spectral`, `kmeans`). |
| `--output-name` | - | No | `adata.h5ad` | Suffix for the generated result file. |

### Advanced Examples

**Finetune + Inference with custom cluster count:**
```bash
spmetatme infer -i sample.h5ad --model-species human --metabolic-model breast_cancer --finetune --epochs 20 --n-clusters 5
```

**Using a custom method for clustering:**
```bash
spmetatme infer -i sample.h5ad --metabolic-model breast_cancer --method leiden
```

**List available metabolic models directly from infer:**
```bash
spmetatme infer --list-models
```

---

## 2. Base Model Pretraining (`spmetatme pretrain`)

Train a new base model from scratch using multiple spatial transcriptomics datasets.

### Basic Usage
```bash
spmetatme pretrain --training-list data/*.h5ad --metabolic-model human_gem --repo-id MyRepo/my-model
```

### Key Parameters
| Parameter | Short | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `--training-list` | `-t` | Yes | - | Path or glob pattern to training `.h5ad` files. |
| `--metabolic-model` | `-m` | Yes | - | Name of the metabolic model to use for training. |
| `--repo-id` | - | Yes | - | The ID of the repository/folder to save the results. |
| `--preprocess / --no-preprocess` | - | No | `True` | Whether to preprocess the training data. |
| `--push-to-hub / --no-push-to-hub` | - | No | `False` | Whether to push the final model to Hugging Face Hub. |
| `--epochs` | - | No | `20` | Number of training epochs. |
| `--save-dir` | - | No | `output/...` | Local directory to save model checkpoints. |

---

## Tip: Available Metabolic Models

You can always list the available metabolic models that `spMetaTME` supports for inference with:

```bash
spmetatme list-metabolic-models
```