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

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:

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

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

marin --help

This outputs available subcommands and confirms the Click group registration defined in 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, manages training workflows:

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, wraps shell commands with built-in profiling utilities:

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, checks data integrity against schemas:

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:

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:

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.

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:

# 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:

from .awesome import awesome  # noqa: F401

3. Ensure entry-point registration in 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, profiling/cli.py, validate/validate.py, and 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.

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.

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), profiling for performance analysis (source: lib/marin/src/marin/profiling/cli.py), validate for dataset schema validation (source: lib/marin/src/marin/validate/validate.py), and inference for model serving (source: 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. Subcommand implementations reside in specific files: lib/marin/src/marin/experiment/cli.py for experiments, lib/marin/src/marin/profiling/cli.py for profiling, lib/marin/src/marin/validate/validate.py for validation, and 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. The CLI discovers these commands automatically, making them available as marin <module_name> <command> without modifying existing code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}