Mai CLI

mai 是 Mai 平台的命令行工具，可在本地完成模型、数据集、文件和镜像的下载、上传、提交、推送。

如果需要完整命令说明，请查看 README.full.md。

快速开始

1. 安装

适合已经有 Python 3.12+ 的环境：

pip install maind
mai --help

如果在 Windows 上看到 mai.exe is installed ... which is not on PATH，或者运行 mai 提示“不是内部或外部命令”，可以先用不依赖 PATH 的方式运行：

python -m mai --help
python -m mai install

也可以把 Python 用户脚本目录加入 PATH，然后重新打开终端：

$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$scripts", "User")

如果需要使用 download、connect、repo push 等工作区命令，安装后先检查并安装本机依赖：

mai install --check
mai install

也可以用 pipx 隔离安装：

pipx install maind
mai --help

2. 登录

交互式登录：

mai login

非交互式登录：

mai login --url https://your-domain --username <USERNAME> --password <PASSWORD>

3. 下载模型或数据集

下载模型：

mai download --model "Qwen2.5-7B-Instruct" --version main

下载数据集：

mai download --dataset "my-dataset" --version main

指定下载目录：

mai download --model "Qwen2.5-7B-Instruct" --version main --dir ./workspace/qwen

常用操作

创建并上传模型

创建模型并初始化本地工作区：

mai create --model "my-model" --description "demo model"
mai connect --model "my-model" --version main
cd ./my-model

把文件放入目录后提交并推送：

mai repo status
mai repo add
mai repo commit -m "update model files"
mai repo push

创建并上传数据集

mai create --dataset "my-dataset" --description "demo dataset"
mai connect --dataset "my-dataset" --version main
cd ./my-dataset

把文件放入目录后提交并推送：

mai repo add
mai repo commit -m "update dataset files"
mai repo push

发布已有本地目录

如果模型或数据集文件已经在本地目录中，可以用 publish 一次完成连接、添加、提交和推送。

发布模型目录：

mai publish --dir ./local-model --model "my-model" --version main -m "publish model"

发布数据集目录：

mai publish --dir ./local-dataset --dataset "my-dataset" --version main -m "publish dataset"

从 Hugging Face 或 ModelScope 同步

从 Hugging Face 同步模型到平台：

mai sync --model hf://Qwen/Qwen2.5-7B --name "qwen2.5-7b" --version main

从 ModelScope 同步数据集到平台：

mai sync --dataset ms://org/my-dataset --name "my-dataset" --version main

文件和镜像

上传文件：

mai file upload ./data.csv --scope personal

构建平台镜像：

mai image build --repo my-image --tag latest --method dockerfile --dockerfile-url https://example.com/Dockerfile

复制镜像：

mai image copy source:tag target:tag

预置资源示例

仓库内置了与 falsework 平台预置资源一致的 seed 示例，可直接 dry-run 验证：

mai seed apply --config examples/seed/config.yaml --resources-dir /tmp/mai-seed-resources --dry-run

Docker 环境

如果不想在宿主机安装 Python、Git、DVC、ModelScope、Hugging Face CLI 等依赖，可以直接使用 Docker 镜像。

docker run --rm -it \
  -v "$PWD":/workspace \
  -v "$HOME/.config/mai":/root/.config/mai \
  -w /workspace \
  harbor.mindreon.com/baize/mai-cli:release-v0.1.0 \
  bash

进入容器后直接使用：

mai --help
mai login

进阶：项目状态和切换

熟悉基础命令后，如果账号下有多个项目，可以查看当前项目状态：

mai status

查看可切换项目：

mai project list

切换当前项目：

mai project use <项目名或项目ID>

切换项目后，后续 create、download、connect、repo push 等命令都会使用新的项目上下文。

常用环境变量

变量	说明
`MAI_API_URL`	平台地址
`MAI_AUTH_TOKEN`	登录 token，优先级高于本地配置文件
`MAI_CONFIG_DIR`	配置文件目录，默认 `~/.config/mai`

Metadata

Release files for maind 0.1.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maind 0.1.9
File	Size	Uploaded
maind-0.1.9.tar.gz	249.4 kB	Jul 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for maind 0.1.9
File	Interpreter	ABI	Platform	Reset
maind-0.1.9-py3-none-any.whl 69.1 kB Jul 9, 2026	Python 3	none	any	Details

Total release size: 318.5 kB

Release files / maind-0.1.9.tar.gz

Download URL	maind-0.1.9.tar.gz
Size	249.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`a7ff21b9a14aa67c51e117b92687c0f697b9455c5ea706af43b1efabf15f68d1`
BLAKE2b-256 checksum How to use checksums	`a73b3746f9c185bb7aeb33f78abb13c69af8a33772f50731377bbe4fc0d22de0`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / maind-0.1.9-py3-none-any.whl

Download URL	maind-0.1.9-py3-none-any.whl
Size	69.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a54d7f5d057fbae1ee80a0c4d556efcc0528b68d981ad55aeb849e38af66874a`
BLAKE2b-256 checksum How to use checksums	`5c789e489d1f9f81540c9577ee48d91c33cf6900dd88532b7c7beec97712cd41`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`