@lvxintao/mt-mlx-cli

v0.5.6

Published

6 days ago

CLI tool for MLX model training platform

Downloads

2,604

0High
0Medium
0Low

lvxintao

mt-mlx-cli

CLI tool for MLX (Meituan ML eXchange) model training platform. Provides authentication, training task management, and configuration via command line.

Installation

npm install
npx playwright install chromium
npm run build

Or link globally for convenience:

npm link

Quick Start

# 1. Login via SSO browser flow
mt-mlx-cli login

# 3. Create and start a training task
mt-mlx-cli train --sample-from 2026-04-01 --sample-to 2026-04-15 --name "my-task"

# 4. Evaluate a model version
mt-mlx-cli eval --algo-id 38152 --model-version 20260514130700670339 --sample-from 2026-04-22 --sample-to 2026-04-22

# 5. Logout when done
mt-mlx-cli logout

Commands

`login`

Authenticate with the MLX platform via SSO. Opens a Chromium browser for SSO login, captures cookies for subsequent API calls.

mt-mlx-cli login
mt-mlx-cli login --verbose          # Enable verbose browser traffic logging
mt-mlx-cli login --url "<SSO_URL>"  # Custom SSO URL

| Flag | Description | Default | |------|-------------|---------| | --url | SSO login URL | MLX platform SSO | | --verbose | Enable verbose logging of browser traffic | false |

`train`

Create and start a model training task. Supports full parameter customization via CLI flags or JSON config file.

mt-mlx-cli train \
  --sample-from 2026-04-01 \
  --sample-to 2026-04-15 \
  --name "my-task"

Basic Parameters

| Flag | Description | Default | |------|-------------|---------| | --algo-id <id> | Algorithm ID | 40792 | | --name <name> | Task name | algo_{id}_{date} | | --sample-path <path> | Sample data path (viewfs) | viewfs://hadoop-meituan/... | | --sample-from <date> | Sample start date (YYYY-MM-DD) | (required) | | --sample-to <date> | Sample end date (YYYY-MM-DD) | (required) | | --label-rule <rule> | Label parsing rule | 0:-1:1;1:0:1;... |

Resource Parameters

| Flag | Description | Default | |------|-------------|---------| | --group-id <id> | Hadoop group ID | 5 | | --worker-num <n> | Number of workers | 160 | | --worker-memory <mem> | Memory per worker (e.g. 2048m) | 2048m | | --worker-vcore <n> | CPU cores per worker | 96 | | --executor-memory <mem> | Executor memory (e.g. 1024m) | 1024m | | --executor-vcore <n> | Executor CPU cores | 2 |

Thread Parameters

| Flag | Description | Default | |------|-------------|---------| | --data-reader-threads <n> | Data reader thread count | 80 | | --data-parser-threads <n> | Data parser thread count | 15 | | --train-thread-num <n> | Training thread count | 1 |

Training Parameters

| Flag | Description | Default | |------|-------------|---------| | --epoch <n> | Training epochs | 1 | | --batch-size <n> | Training batch size | 384 | | --shuffle-size <n> | Shuffle buffer size | 10000 | | --eval-batch-size <n> | Evaluation batch size | 500000 |

PS (Parameter Server) Parameters

| Flag | Description | Default | |------|-------------|---------| | --ps-worker-num <n> | PS worker count | 29 | | --ps-worker-cpu <n> | PS CPU cores | 2 | | --ps-worker-mem <n> | PS memory (MB) | 4096 |

Advanced Parameters

| Flag | Description | Default | |------|-------------|---------| | --mode <mode> | Execution mode (cpu/gpu) | cpu | | --hparams <json> | Model hyperparameters as JSON string | [] | | --yaml <path> | Load config from YAML file (supports nested sections) | - | | --template <taskId> | Base config off an existing task ID | - | | --config <path> | Load all parameters from JSON file | - | | --verbose | Enable verbose logging | false |

Examples

# Basic: only required params, rest from defaults
mt-mlx-cli train --sample-from 2026-04-01 --sample-to 2026-04-15

# Custom epoch and batch size
mt-mlx-cli train \
  --sample-from 2026-04-01 \
  --sample-to 2026-04-15 \
  --epoch 5 --batch-size 512

# Full resource customization
mt-mlx-cli train \
  --sample-from 2026-04-01 \
  --sample-to 2026-04-15 \
  --worker-num 80 --worker-memory 4096m \
  --ps-worker-num 15 --ps-worker-mem 8192

# Using a JSON config file (overrides CLI flags)
mt-mlx-cli train --sample-from 2026-04-01 --sample-to 2026-04-15 --config train.json

# Using --template to copy an existing task's config
mt-mlx-cli train --template 660152 --sample-from 2026-05-01 --sample-to 2026-05-15

# Combining --template with --yaml for targeted overrides
mt-mlx-cli train --template 660152 --yaml overrides.yaml

YAML Nested Config

The --yaml flag supports both flat key-value YAML (backward compatible) and nested config sections for full access to all 80+ task parameters:

# example-config.yaml
name: my_task
sample_from: 2026-05-01
sample_to: 2026-05-15
hadoop_config:
  exceeding_type: true
  group_id: 10
  gauc_hadoop_queue: "default"
run_config:
  mode: gpu
  worker_num: 80
  storage_mode: 2
  parallelism: 100
worker_config:
  batch_size: 512
  parse_thread_num: 3
  label_dim: 2
train_config:
  checkpoint: true
  run_gauc: false
  day_shrink: true
model_config:
  hparams:
    - lr: 0.001
      dropout: 0.1
    - lr: 0.0001
      dropout: 0.2

All 5 config sections are supported: hadoop_config, run_config, train_config, model_config, worker_config. YAML values perform deep merge — you only need to specify the fields you want to override; the rest use their defaults.

`train config`

View the full configuration (hyperparameters) of a training task by ID. Displays all ~80+ parameters grouped by config section.

mt-mlx-cli train config 660152
mt-mlx-cli train config 660152 --verbose

| Flag | Description | Default | |------|-------------|---------| | --verbose | Enable verbose logging | false |

Output sections: Worker Config → Model Config → Train Config → Run Config → Hadoop Config. Date tuples are formatted as YYYY-MM-DD, nested objects are indented.

`train status`

Query the status of a training task by ID.

mt-mlx-cli train status 660152
mt-mlx-cli train status 660152 --log     # Include task logs
mt-mlx-cli train status 660152 --verbose # Enable verbose logging

| Flag | Description | Default | |------|-------------|---------| | --log | Show task logs for the latest attempt | false | | --verbose | Enable verbose logging | false |

`train stop`

Stop a running training task by ID.

mt-mlx-cli train stop 660164

| Flag | Description | Default | |------|-------------|---------| | --verbose | Enable verbose logging | false |

`train metrics`

View training metrics (loss, AUC, etc.) for a training task. Displays aggregated metrics per session (averaged across all workers).

mt-mlx-cli train metrics 660463
mt-mlx-cli train metrics 660463 --verbose

| Flag | Description | Default | |------|-------------|---------| | --verbose | Enable verbose logging | false |

Output columns: SESSION, EPOCH, AUC, AVG_LOSS, COPC, MAE, MSE, AVG_LABEL, AVG_PRED. Values are weighted by evalBatchCount to match the frontend's "整体加权平均" aggregation.

`eval`

Create and start a model evaluation task. Eval tasks use the same backend as training but require a model version to evaluate.

mt-mlx-cli eval \
  --algo-id 38152 \
  --model-version 20260514130700670339 \
  --sample-from 2026-04-22 \
  --sample-to 2026-04-22

If --model-version is omitted, the latest published version for the algo is used automatically. The value should be the model_version from the train config (e.g. 20260514130700670339) — the CLI internally resolves it to the database ID.

Basic Parameters

| Flag | Description | Default | |------|-------------|---------| | --algo-id <id> | Algorithm ID | (required) | | --model-version <version> | Model version (model_value from train config) | Auto-latest | | --name <name> | Task name | algo_{id}_{date} | | --sample-path <path> | Sample data path (viewfs) | viewfs://hadoop-meituan/... | | --sample-from <date> | Sample start date (YYYY-MM-DD) | (required) | | --sample-to <date> | Sample end date (YYYY-MM-DD) | (required) | | --label-rule <rule> | Label parsing rule | 0:-1:1;1:0:1;... |

Eval-Specific Parameters

| Flag | Description | Default | |------|-------------|---------| | --run-gauc | Run GAUC analysis | true | | --run-pfi | Run feature importance analysis | false | | --separate-result-by-date | Separate results by date | true | | --eval-feature-sparse-col-ids <ids> | Eval sparse feature column IDs | null | | --eval-feature-dense-col-offsets <offsets> | Eval dense feature column offsets | null | | --eval-feature-mix-col-pairs <pairs> | Eval mixed feature column pairs | null |

Resource parameters (--worker-num, --batch-size, etc.) are identical to train. See mt-mlx-cli eval --help for the full list.

Examples

# Evaluate latest published version (auto-resolved)
mt-mlx-cli eval --algo-id 38152 --sample-from 2026-04-22 --sample-to 2026-04-22

# Evaluate specific model version
mt-mlx-cli eval --algo-id 38152 --model-version 20260514130700670339 --sample-from 2026-04-22 --sample-to 2026-04-22

# Using a YAML config file
mt-mlx-cli eval --yaml example-eval-config.yaml

# With GAUC analysis enabled explicitly
mt-mlx-cli eval --algo-id 38152 --model-version 20260514130700670339 --sample-from 2026-04-22 --sample-to 2026-04-22 --run-gauc

`eval status`

Query the status of an evaluation task by ID.

mt-mlx-cli eval status 662109
mt-mlx-cli eval status 662109 --log     # Include task logs
mt-mlx-cli eval status 662109 --verbose # Enable verbose logging

`eval stop`

Stop a running evaluation task by ID.

mt-mlx-cli eval stop 662109

`eval metrics`

View evaluation metrics (loss, AUC, etc.) for an evaluation task.

mt-mlx-cli eval metrics 662109
mt-mlx-cli eval metrics 662109 --verbose

Output columns and aggregation are identical to train metrics.

`config`

Manage CLI configuration stored in ~/.mt-cli/config.json. Configuration values serve as persistent defaults for train command parameters.

# List all config values
mt-mlx-cli config list

# Get a specific value
mt-mlx-cli config get algoId

# Set a value (persisted as default)
mt-mlx-cli config set algoId 40793
mt-mlx-cli config set samplePath "viewfs://hadoop-meituan/user/..."

| Subcommand | Description | |------------|-------------| | config get <key> | Get a configuration value | | config set <key> <value> | Set a configuration value | | config list | List all configuration values |

`model`

Manage MLX algorithms.

`model get`

Download algorithm source files to the current directory. Creates a folder named after the algorithm containing all code files.

mt-mlx-cli model get 40801
mt-mlx-cli model get 40801 --verbose  # Enable verbose logging

| Flag | Description | Default | |------|-------------|---------| | --verbose | Enable verbose logging | false |

`model fork`

Fork an existing algorithm with a new name. Returns the new algorithm ID and name.

mt-mlx-cli model fork 40801 --name "my-forked-algo"
mt-mlx-cli model fork 40801 --name "my-forked-algo" --verbose

| Flag | Description | Default | |------|-------------|---------| | --name <name> | New algorithm name | (required) | | --verbose | Enable verbose logging | false |

`model new`

Create a new algorithm from local source files. Automatically removes preset platform files after creation.

mt-mlx-cli model new --name "my-algo" --files model.py custom_layer.py feature_conf.py
mt-mlx-cli model new --name "my-algo" --files model.py --description "My algorithm description"
mt-mlx-cli model new --name "my-algo" --files model.py custom_layer.py --verbose

| Flag | Description | Default | |------|-------------|---------| | --name <name> | Algorithm name | (required) | | --files <files...> | Source files to upload | (required) | | --description <desc> | Algorithm description | Created via CLI | | --verbose | Enable verbose logging | false |

`model update`

Update or add files in an existing algorithm. Files with matching names are replaced; new files are added to the codeTree. If model.py is uploaded and the current main file is not model.py, it automatically becomes the new main file.

mt-mlx-cli model update 40801 --files model.py custom_layer.py
mt-mlx-cli model update 40801 --files model.py new_file.py --verbose

| Flag | Description | Default | |------|-------------|---------| | --files <files...> | Source files to update/add | (required) | | --verbose | Enable verbose logging | false |

`model run`

Run an algorithm by ID, or check latest run status with --status.

mt-mlx-cli model run 41755
mt-mlx-cli model run 41755 --status   # Check latest run status and logs
mt-mlx-cli model run 41755 --verbose  # Enable verbose logging

| Flag | Description | Default | |------|-------------|---------| | --status | Show latest run status and logs | false | | --verbose | Enable verbose logging | false |

`model publish`

Publish an algorithm to a repository (private by default). The algorithm must have a successful run before publishing.

mt-mlx-cli model publish 41757
mt-mlx-cli model publish 41757 --public   # Publish to public repository
mt-mlx-cli model publish 41757 --verbose  # Enable verbose logging

| Flag | Description | Default | |------|-------------|---------| | --public | Publish to public repository | false (private) | | --verbose | Enable verbose logging | false |

`logout`

Clear stored credentials and session data.

mt-mlx-cli logout

`update`

Check for updates and update the CLI to the latest version.

mt-mlx-cli update              # Check and prompt if update available
mt-mlx-cli update --check      # Only check, do not update
mt-mlx-cli update --yes        # Auto-update without confirmation

| Flag | Description | Default | |------|-------------|---------| | --check | Only check for updates, do not update | false | | --yes | Auto-update if a new version is available | false |

Examples

# Check if update is available
mt-mlx-cli update

# Only check version without updating
mt-mlx-cli update --check

# Update directly without confirmation
mt-mlx-cli update --yes

Configuration Files

`~/.mt-cli/config.json`

User configuration with persistent defaults. Keys matching TrainConfig fields become defaults for the train command.

{
  "ssoUrl": "https://ssosv.sankuai.com/sson/login?client_id=...",
  "defaults": {
    "algoId": 40792,
    "samplePath": "viewfs://hadoop-meituan/user/...",
    "labelRule": "0:-1:1;1:0:1;2:0:1;3:0:1;4:0:1;5:0:1;6:1:1",
    "workerNum": 80,
    "batchSize": 512
  }
}

`~/.mt-cli/credentials.json`

Auto-managed cookie storage from SSO login. Do not edit manually.

Parameter Priority

When resolving parameters, the CLI follows this priority (highest to lowest):

CLI flags (e.g. --epoch 3, --run-gauc)
YAML/JSON config files (--yaml, --config) — YAML supports nested sections for full parameter access
--template <taskId> taskConfig (if provided)
User config (~/.mt-cli/config.json defaults)
Built-in defaults (hardcoded values matching the MLX Web UI)

This applies to both train and eval commands.

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev -- train --help

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Architecture

mt-mlx-cli/
├── src/
│   ├── api/
│   │   ├── client.ts      # HTTP client with cookie injection, retry, circuit breaker
│   │   ├── training.ts    # Training API methods (create, run, list, metrics, etc.)
│   │   ├── evaluation.ts  # Evaluation API methods (create, run, status, stop, metrics)
│   │   └── model.ts       # Algorithm API methods (detail, list)
│   ├── auth/
│   │   ├── browser.ts     # Playwright SSO login via Chromium
│   │   └── token.ts       # Auth state management
│   ├── cli/
│   │   ├── commands/
│   │   │   ├── login.ts   # Login command
│   │   │   ├── train.ts   # Train command
│   │   │   ├── eval.ts    # Eval command
│   │   │   ├── config.ts  # Config command (get/set/list)
│   │   │   ├── logout.ts  # Logout command
│   │   │   ├── update.ts  # Update command (version check & auto-update)
│   │   │   └── model.ts   # Model command (get/fork/new/update/run/publish)
│   │   └── index.ts       # CLI entry point
│   ├── config/
│   │   ├── defaults.ts    # Built-in default values
│   │   └── resolver.ts    # Parameter resolution (CLI > config > defaults)
│   ├── utils/
│   │   ├── config.ts      # User config store
│   │   ├── credentials.ts # Credential storage with file permissions
│   │   ├── format.ts      # Metrics table formatting
│   │   ├── status.ts      # Task status formatting
│   │   └── yaml.ts        # YAML parser with nested section support
│   └── types.ts           # Shared TypeScript interfaces
├── tests/
│   └── unit/
│       ├── credential.test.ts
│       ├── config.test.ts
│       ├── eval-config.test.ts
│       ├── format.test.ts
│       ├── metrics.test.ts
│       └── update.test.ts
└── package.json

API Details

The CLI communicates with the MLX platform API at https://mlx.sankuai.com/mlx/api/. Key endpoints:

| Endpoint | Method | Purpose | |----------|--------|---------| | /user/info | POST | Get user information | | /train/create | POST | Create training task | | /train/run/{id} | POST | Start training task | | /train/list | POST | List training tasks | | /train/status/{id} | POST | Get task status | | /metric/list | GET | Get training metrics | | /algorithm-model/{id} | GET | Get algorithm detail with source code | | /algorithm-model/list | GET | List algorithms with pagination | | /algorithm-model/fork | POST | Fork an algorithm to create a copy | | /algorithm-model/add-or-update | POST | Create or update an algorithm | | /algorithm-model/run | PUT | Run an algorithm | | /algorithm-model/run-result/{resultId}/{attemptId} | GET | Get run logs and status | | /algorithm-model/push | PUT | Publish an algorithm to repository |

Authentication is via cookies obtained through SSO browser login. The HTTP client includes:

Circuit breaker: 10 consecutive 5xx errors triggers 5-minute cooldown
Retry with exponential backoff: 3 retries for 5xx/network errors
401 handling: Max 2 consecutive 401 retries before requiring re-login

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

mt-mlx-cli

Installation

Quick Start

Commands

login

train

Basic Parameters

Resource Parameters

Thread Parameters

Training Parameters

PS (Parameter Server) Parameters

Advanced Parameters

Examples

YAML Nested Config

train config

train status

train stop

train metrics

eval

Basic Parameters

Eval-Specific Parameters

Examples

eval status

eval stop

eval metrics

config

model

model get

model fork

model new

model update

model run

model publish

logout

update

Examples

Configuration Files

~/.mt-cli/config.json

~/.mt-cli/credentials.json

Parameter Priority

Development

Architecture

API Details

`login`

`train`

`train config`

`train status`

`train stop`

`train metrics`

`eval`

`eval status`

`eval stop`

`eval metrics`

`config`

`model`

`model get`

`model fork`

`model new`

`model update`

`model run`

`model publish`

`logout`

`update`

`~/.mt-cli/config.json`

`~/.mt-cli/credentials.json`