# How to Use the Marin CLI: Command Reference and Workflow Guide

> Master the Marin CLI with this guide to its commands and workflows. Manage training, profiling, validation, and inference for your ML projects efficiently.

- Repository: [The Marin Project/marin](https://github.com/marin-community/marin)
- Tags: how-to-guide
- Published: 2026-08-29

---

**The Marin CLI is a Click-based command-line interface that provides hierarchical subcommands—`experiment`, `profiling`, `validate`, and `inference`—to manage training workflows, profile performance, validate data, and serve models from the marin-community/marin repository.**

The Marin CLI serves as the primary entry point for interacting with the Marin platform from the terminal. Built with the **Click** framework and distributed as the `marin` executable after installation, this tool enables machine learning engineers to orchestrate experiments, validate datasets, and deploy models through a modular command structure defined in `lib/marin/src/marin/`.

## Getting Started with the Marin CLI

Install the workspace in editable mode from the repository root using `uv` or `pip`:

```bash
cd /path/to/marin
uv pip install -e .

```

Verify the installation by checking the top-level help menu:

```bash
marin --help

```

This outputs available subcommands and confirms the Click group registration defined in [`lib/marin/src/marin/__init__.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/__init__.py).

## Core Marin CLI Commands and Usage

The CLI organizes functionality into domain-specific subcommands. Each subcommand is implemented as a separate module under `lib/marin/src/marin/`.

### Launch Training Experiments

The `experiment` subcommand, implemented in [`lib/marin/src/marin/experiment/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/experiment/cli.py), manages training workflows:

```bash
marin experiment launch \
    --config experiments/tutorials/train_tiny_model.py \
    --device cpu

```

- **`experiment launch`** instantiates an `Experiment` object from a Python configuration file.
- **`--device`** accepts `cpu`, `gpu`, or `tpu` to specify the execution hardware.

### Profile Performance Runs

The `profiling` subcommand, defined in [`lib/marin/src/marin/profiling/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/profiling/cli.py), wraps shell commands with built-in profiling utilities:

```bash
marin profiling run \
    --output profile.json \
    --command "python my_script.py"

```

This executes the specified command and writes performance metrics to the designated JSON file.

### Validate Datasets

The `validate` subcommand, located in [`lib/marin/src/marin/validate/validate.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/validate/validate.py), checks data integrity against schemas:

```bash
marin validate dataset \
    --manifest data/manifest.json \
    --schema data/schema.yaml

```

This surfaces missing fields or type mismatches before training begins.

### Serve Models for Inference

The `inference` subcommand supports model serving backends such as VLLM or Iris through [`lib/marin/src/marin/inference/serve_cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/inference/serve_cli.py):

```bash
marin inference serve \
    --model my_model \
    --port 8080

```

This starts a serving process that listens on the specified port for inference requests.

## Accessing Command-Line Help

Every command supports Click's standard help flags for self-discovery. The help text is auto-generated from docstrings in the source files:

```bash
marin <subcommand> --help
marin <subcommand> <nested-command> --help

```

For example, `marin experiment launch --help` prints parameter descriptions sourced directly from [`lib/marin/src/marin/experiment/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/experiment/cli.py).

## Extending the Marin CLI with Custom Commands

The modular architecture allows developers to add new subcommands without modifying core logic.

1. **Create a new module** under `lib/marin/src/marin/` with Click command definitions:

```python

# lib/marin/src/marin/awesome/cli.py

import click

@click.group()
def awesome():
    """Awesome utilities."""
    pass

@awesome.command()
@click.argument("name")
def greet(name):
    """Print a friendly greeting."""
    click.echo(f"Hello, {name}!")

```

2. **Register the import** in [`lib/marin/src/marin/__init__.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/__init__.py):

```python
from .awesome import awesome  # noqa: F401

```

3. **Ensure entry-point registration** in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml) under `[project.scripts]` to expose the `marin` executable.

The new command becomes available as `marin awesome greet <name>`.

## Summary

- The **Marin CLI** provides a hierarchical command structure built on Click for managing ML workflows in marin-community/marin.
- Install via `uv pip install -e .` to register the `marin` executable globally.
- Core subcommands include `experiment` (training), `profiling` (performance), `validate` (data quality), and `inference` (serving).
- Source implementations reside in `lib/marin/src/marin/` with specific modules for each domain: [`experiment/cli.py`](https://github.com/marin-community/marin/blob/main/experiment/cli.py), [`profiling/cli.py`](https://github.com/marin-community/marin/blob/main/profiling/cli.py), [`validate/validate.py`](https://github.com/marin-community/marin/blob/main/validate/validate.py), and [`inference/serve_cli.py`](https://github.com/marin-community/marin/blob/main/inference/serve_cli.py).
- Use `--help` flags to explore command options auto-generated from source docstrings.
- Extend functionality by adding modules under `lib/marin/src/marin/` and importing them in the top-level [`__init__.py`](https://github.com/marin-community/marin/blob/main/__init__.py).

## Frequently Asked Questions

### How do I install the Marin CLI?

Install the marin-community/marin repository in editable mode using `uv pip install -e .` from the workspace root. This registers the `marin` entry point globally, allowing you to invoke the CLI from any directory according to the `[project.scripts]` table in [`pyproject.toml`](https://github.com/marin-community/marin/blob/main/pyproject.toml).

### What subcommands are available in the Marin CLI?

The CLI exposes four primary subcommands: `experiment` for training workflows (source: [`lib/marin/src/marin/experiment/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/experiment/cli.py)), `profiling` for performance analysis (source: [`lib/marin/src/marin/profiling/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/profiling/cli.py)), `validate` for dataset schema validation (source: [`lib/marin/src/marin/validate/validate.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/validate/validate.py)), and `inference` for model serving (source: [`lib/marin/src/marin/inference/serve_cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/inference/serve_cli.py)).

### Where are the Marin CLI command implementations located?

The top-level Click group is defined in [`lib/marin/src/marin/__init__.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/__init__.py). Subcommand implementations reside in specific files: [`lib/marin/src/marin/experiment/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/experiment/cli.py) for experiments, [`lib/marin/src/marin/profiling/cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/profiling/cli.py) for profiling, [`lib/marin/src/marin/validate/validate.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/validate/validate.py) for validation, and [`lib/marin/src/marin/inference/serve_cli.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/inference/serve_cli.py) for inference serving.

### How can I add a custom subcommand to the Marin CLI?

Create a new Python module under `lib/marin/src/marin/` containing Click command definitions, then import the module in [`lib/marin/src/marin/__init__.py`](https://github.com/marin-community/marin/blob/main/lib/marin/src/marin/__init__.py). The CLI discovers these commands automatically, making them available as `marin <module_name> <command>` without modifying existing code.