# 安装与快速开始

# 1. 前置要求

• Node.js >= 22.0.0

# 2. 安装

pnpm add -g @cmtx/cli

验证安装：

cmtx --version

# 3. 命令结构

CLI 命令分为以下几类：

cmtx
├── analyze            # 资源分析命令组
│   ├── images        # 扫描分析目录图片
│   ├── links         # 检测链接可访问性
│   └── check-url     # 检测单个 URL 可访问性
├── image              # 图片管理命令组
│   ├── download      # 下载远程图片
│   ├── upload        # 上传本地图片
│   ├── delete        # 删除指定图片
│   ├── copy          # 复制远程图片
│   ├── move          # 移动远程图片
│   ├── cleanup       # 清理未引用图片
│   └── presign       # 生成预签名 URL
├── format             # Markdown/HTML 转换
├── section-numbers    # 章节编号管理
│   ├── add           # 添加编号
│   └── remove        # 移除编号
├── publish            # 执行 preset
└── config             # 配置管理
    ├── init          # 创建配置
    └── show          # 显示模板

# 4. 基本用法

cmtx <command> [options]

# 5. 查看帮助

cmtx --help
cmtx image --help
cmtx image copy --help
cmtx config --help
cmtx publish --help

# 6. 配置文件

# 6.1. 创建配置文件

cmtx config init

使用自定义文件名：

cmtx config init --output-file .cmtx/config.yaml

强制覆盖已存在的文件：

cmtx config init --force

# 6.2. 显示配置模板

cmtx config show

# 6.3. 配置文件发现

未指定 --config 时，CLI 会自动向上遍历目录查找：

1. cmtx.config.yaml
2. .cmtx/config.yaml

最多遍历 10 层目录。

# 6.4. 环境变量

凭证可通过环境变量传入，避免在命令历史中暴露敏感信息。

完整环境变量清单请参考 CFG-001 配置参考。

CMTX_ALIYUN_ACCESS_KEY_ID=your_key \
CMTX_ALIYUN_ACCESS_KEY_SECRET=your_secret \
CMTX_ALIYUN_BUCKET=my-bucket \
cmtx image upload ./article.md --prefix blog/images

# 7. 快速示例

# 分析目录中的图片
cmtx analyze images ./docs --depth 2

# 检测文件中的链接
cmtx analyze links ./docs/article.md

# 上传图片到阿里云 OSS
cmtx image upload ./article.md --provider aliyun-oss --prefix blog/images

# 清理未引用的图片
cmtx image cleanup ./assets --strategy trash

# 为 Markdown 添加章节编号
cmtx section-numbers add ./article.md --in-place