---
name: mf
description: Use the muffuletta (mf) CLI to interact with Geneva clusters, jobs, manifests, and Kubernetes resources. Invoke this skill when the user wants to run mf commands, check job status, list clusters, stream logs, or troubleshoot Geneva.
---

# muffuletta (mf) CLI - Geneva Command Line Interface

muffuletta is a CLI tool for LanceDB Geneva (Multimodal Feature Engineering). The binary is `mf`.

## Prerequisites

- A valid kubeconfig (`kubectl` must work against the target cluster)
- Cloud credentials (must have AWS, GCP, or Azure cloud credentials set)
For example, in AWS:
```bash
unset AWS_ACCESS_KEY_ID
export AWS_PROFILE=lance-devland
aws eks update-kubeconfig --region us-east-1 --name lancedb --role-arn arn:aws:iam::054483968661:role/lancedb_eks_cluster_access
```
- The CLI installed: `cd src/cli && uv pip install -e .`

## Configuration

Configuration is stored in `~/.geneva/config.json`.

```bash
# Interactive configuration (prompts for db_uri and namespace)
mf configure

# Set options directly
mf configure --db-uri s3://my-bucket/geneva --namespace geneva

# Show current configuration
mf configure --show
```

Required config:
- `db_uri`: Geneva database URI (e.g. `s3://my-bucket/geneva`)
- `namespace`: Kubernetes namespace (defaults to `geneva`)

## Connection

The CLI connects to Geneva by port-forwarding to the `geneva-console-api` Kubernetes service in the configured namespace. This happens automatically when running any command that needs the API.

## Global Options

All commands support:
- `--output` / `-o`: Output format (`table`, `json`, `text`). Default: `table` for list commands, `text` for get commands.
- `--namespace` / `-n`: Override Kubernetes namespace
- `--context`: Override Kubernetes context
- `--debug`: Enable debug logging (includes httpx request/response logs)
- `--version` / `-v`: Show version

## Commands

### Clusters

```bash
# List all Geneva clusters
mf clusters list
mf clusters list -o json

# Get details of a specific cluster (shows KubeRay config, head/worker groups)
mf clusters get <cluster-name>
mf clusters get <cluster-name> -o json
```

### Manifests

```bash
# List all manifests
mf manifests list

# Get manifest details (shows pip deps, images, py_modules, zips)
mf manifests get <manifest-name>
mf manifests get <manifest-name> -o json
```

### Jobs

```bash
# List jobs (defaults to last 7 days)
mf jobs list

# Filter by status: PENDING, RUNNING, DONE, FAILED, CANCELLED
mf jobs list --status running
mf jobs list -s failed

# Filter by time range (units: m=minutes, h=hours, d=days, w=weeks)
mf jobs list --since -3h
mf jobs list --since -2d --until -1h

# Show all jobs (disable 7-day default filter)
mf jobs list --all
mf jobs list -a

# Limit results
mf jobs list --limit 10
mf jobs list -l 5

# Auto-refresh every 10 seconds (Ctrl+C to stop)
mf jobs list --watch
mf jobs list -w

# Combine filters
mf jobs list -s running --since -1d -w

# Get job details (shows config, events timeline, metrics progress)
mf jobs get <job-id>
mf jobs get <job-id> -o json
mf jobs get <job-id> --watch
```

### RayClusters (Kubernetes)

```bash
# List KubeRay RayClusters
mf rayclusters list

# Get RayCluster details
mf rayclusters get <name>
```

### Logs

```bash
# Stream logs from a job (finds pods by job ID label)
mf logs <job-id>

# Stream logs from a specific pod name
mf logs <pod-name>

# Options
mf logs <job-id> --tail 100          # Last 100 lines
mf logs <job-id> --no-follow         # Don't stream, just print
mf logs <job-id> --container <name>  # Specific container (multi-container pods)
mf logs <job-id> -c <name> -f        # Short flags
```

## Source Code

The CLI source is at `src/cli/muffuletta/`:
- `cli.py` - Typer CLI commands and `geneva_client()` context manager
- `k8s.py` - Kubernetes operations (port-forward, pod discovery, log streaming)
- `client.py` - REST client for Geneva Console API (`/api/v1/clusters`, `/api/v1/manifests`, `/api/v1/jobs`)
- `config.py` - Config management (`~/.geneva/config.json`)
- `models.py` - Pydantic models (Cluster, Manifest, Job, RayCluster)
- `formatters.py` - Rich table/text/json output formatting

## Troubleshooting

- **"No database URI configured"**: Run `mf configure` first
- **Port-forward failures**: Check that `kubectl` works and you have creds (`dl`)
- **Debug API calls**: Use `mf --debug <command>` to see HTTP requests/responses
