# Leither CLI 功能文档

**目标受众**: Agent（读后生成 Skill + 执行验证）
**范围**: v2 — 全量 CLI 命令参考
**前提**: Leither 服务已侦听（参见[安装文档](install-doc.md)）
**最后验证**: 2026-07-26，Leither V0.23.65，本地节点

---

## 命令约定

- 所有命令支持 `--json` 输出，Agent 优先使用 `--json` 解析结果
- JSON 输出包裹在统一信封中：`{"exit_code":<int>,"data":<object|null>,"error":<object|null>}`
- `exit_code=0` 表示成功，非零表示错误
- 命令名区分大小写：顶层命令首字母大写（如 `Leither`），子命令小写
- 全局参数：`-k <keyfile>`（密钥）、`-n <node>`（远程节点）、`--json`（JSON 输出）

---

## 1. 网络命令

### 1.1 swarm — P2P 节点管理

| 命令 | 功能 | --json |
|------|------|:--:|
| `swarm peers` | 列出已连接的对等节点 | ✓ |
| `swarm id` | 查看本节点标识（NodeId + PeerId） | — |
| `swarm addrs` | 列出已知节点的网络地址 | ✓ |
| `swarm connect <addr>` | 手动连接节点 | — |
| `swarm disconnect <addr>` | 断开与指定地址的连接 | — |
| `swarm filters` | 管理地址过滤器 | — |
| `swarm local` | 查看本地网络地址 | — |

#### swarm peers — 查询网络节点

```bash
Leither swarm peers --json
```

JSON 输出：

```json
{
  "exit_code": 0,
  "data": {
    "peers": {
      "count": 15,
      "peers": [
        "/ip4/115.206.135.212/tcp/8002/p2p/12D3KooWC3eJNrQZQPVsqKCeXo1fPrR2ELxNzX6LYSEoCnNmjEdF",
        "/ip4/39.100.182.122/tcp/80/p2p/12D3KooWBMZrp7LjaV96KURbKMc69ud9a3RbTjwxm7AoyF8S9HBr"
      ]
    }
  },
  "error": null
}
```

最小可执行示例：

```bash
Leither swarm peers
# /ip4/115.206.135.212/tcp/8002/p2p/12D3KooWC3...
# /ip4/39.100.182.122/tcp/80/p2p/12D3KooWBMZ...
# ... 15 peers
```

#### swarm addrs — 已知节点地址

```bash
Leither swarm addrs --json
```

JSON 输出 (V0.23.61)：

```json
{
  "exit_code": 0,
  "data": {
    "addrs": {
      "nodes": ["12D3KooWC3...", "12D3KooWBM..."],
      "count": 17
    }
  },
  "error": null
}
```

### 1.2 dht — 分布式哈希表

| 命令 | 功能 | --json |
|------|------|:--:|
| `dht netsize` | DHT 网络节点总数 | — |
| `dht show` | DHT 路由表详情（LAN/WAN 分表） | — |
| `dht get <key>` | 从 DHT 读取键值 | — |
| `dht put <key> <value>` | 向 DHT 写入键值 | — |
| `dht findpeer <peerid>` | 查找指定 Peer | — |

---

## 2. 文件命令

### files — MFS 文件系统

| 命令 | 功能 | --json |
|------|------|:--:|
| `files ls <path>` | 列出目录内容 | ✓ |
| `files stat <path>` | 显示文件/目录状态 | ✓ |
| `files cp <src> <dst>` | 复制文件或目录 | — |
| `files mv <src> <dst>` | 移动/重命名 | — |
| `files rm <path>` | 删除文件 | — |
| `files mkdir <path>` | 创建目录 | — |
| `files flush <path>` | 将路径数据刷写到磁盘 | — |
| `files check` | 检查哪些文件本地不可用 | — |

#### files ls — 查询容器内文件

```bash
Leither files ls --json
```

最小可执行示例：

```bash
Leither files ls
# path =  /
# .mm          Dir   0   QmQgDoQW7MMWvL2YT4Z472WB3PVSYKXfYdT1FJewcQxpH5
# README.md    File  950 QmWpZUKrQCeJJJCsa3smLVywKa4Z2SKCjWXxFzFgyrCZXD9
# html         Dir   0   QmcnzUrhN6U7ftuxTuyzmdYKpMpohMtrxBoa4T1T1mrAFN
```

---

## 3. 应用命令

### 3.1 lapp — MApp 管理

| 命令 | 功能 | --json |
|------|------|:--:|
| `lapp uploadapp -k <key> -i <dir>` | 上传并部署 MApp | — |
| `lapp showapp` | 列出所有已部署 MApp | ✓ |
| `lapp showapp -a <name>` | 查看指定 MApp 详情 | ✓ |
| `lapp release -a <name> -k <key> -v <ver>` | 发布到 P2P 网络 | — |
| `lapp backup -a <name>` | 备份应用数据 | — |
| `lapp restore -a <name>` | 从备份恢复应用 | — |
| `lapp delver -a <name>` | 删除指定版本 | — |
| `lapp uploadfile -a <name> -i <file>` | 上传文件到应用 | — |
| `lapp setdomain -a <name>` | 设置应用域名 | — |
| `lapp resetref -a <name>` | 重置应用引用 | — |

#### lapp showapp — 查看 MApp

```bash
Leither lapp showapp --json
```

JSON 输出：

```json
{
  "exit_code": 0,
  "data": {
    "apps": [
      {
        "app_id": "1ZLw8a9HvMnlnDzvo9JtktjW_3j",
        "author": "Nsduu_BPmZztn8WSz68hYAq5tdg",
        "name": "mExplorer",
        "last": "35",
        "url": "http://127.0.0.1:4800/entry?aid=1ZLw8a9HvMnlnDzvo9JtktjW_3j&ver=cur"
      }
    ]
  },
  "error": null
}
```

#### lapp uploadapp — 上传 MApp

```bash
Leither lapp uploadapp ./myapp -k user.key
```

上传成功后返回 AppID。上传后需 `release` 发布版本。

#### lapp release — 发布 MApp

```bash
Leither lapp release -a myapp -k user.key -v 1
```

发布后 MApp 可通过 P2P 网络同步到其他节点，也可通过 HTTP 直调（`ver=release`）。

### 3.2 lpki runapp — 运行 MApp

| 命令 | 功能 |
|------|------|
| `lpki runapp --local <path> <entry> -r <params> -a <key>` | 本地开发调试（推荐） |
| `lpki runapp --id <app-id> <entry>` | 通过容器 ID 运行 |
| `lpki runscript` | 运行脚本 |

```bash
# 开发模式（推荐）—— 本地直接编译执行
Leither lpki runapp --local ./myapp hello -r "name=World" -a user.key
# → Hello, World!

# HTTP 调用（发布后）
curl "http://127.0.0.1:4800/entry?aid=<app-id>&ver=release&entry=hello&name=World"
```

---

## 4. 身份命令

### lpki — PKI 密码学体系

| 命令 | 功能 | --json |
|------|------|:--:|
| `lpki genkey -o <file>` | 生成密钥对 | — |
| `lpki genpk -k <key>` | 从私钥导出公钥 | — |
| `lpki gencert -k <key> -m <meta> -o <file>` | 生成 CA 证书 | — |
| `lpki genpkcert` | 生成公钥证书 | — |
| `lpki gensid` | 生成会话 ID | — |
| `lpki signppt` | PPT 令牌签名 | — |
| `lpki verifyppt` | 验证 PPT 令牌 | — |
| `lpki addkey` | 将密钥添加到节点 | — |
| `lpki id` | 显示节点 ID | — |
| `lpki show` | 显示对象信息 | — |
| `lpki grantservice` | 向目标节点授权服务 | — |
| `lpki reqservice` | 请求服务授权 | — |
| `lpki shell` | 交互式 Shell | — |

#### 生成身份密钥（首次使用）

```bash
Leither lpki genkey -o user.key                    # 生成密钥
Leither lpki gencert -k user.key -m "name=user" -o user.ca  # 颁发证书
```

备注：CLI 命令名是 `gencert`（不是 `genca`）。支持 `--key-type sodium|sodiumv2`。

---

## 5. 存储命令

### mimei — MiMei 去中心化存储

| 命令 | 功能 | --json |
|------|------|:--:|
| `mimei create` | 创建新的 MiMei 数据对象 | — |
| `mimei add <file> <mid>` | 添加文件到 MiMei | — |
| `mimei get <mid>` | 读取 MiMei 内容 | — |
| `mimei ls <mid>` | 列出 MiMei 目录 | — |
| `mimei show <mid>` | 显示 MiMei 详情 | — |
| `mimei sync <mid>` | 跨节点同步数据 | — |
| `mimei backup <mid>` | 备份当前版本 | — |
| `mimei restore <mid>` | 从备份恢复 | — |
| `mimei diagnose <mid>` | 健康检查 | ✓ |
| `mimei repair <mid>` | 修复（MAC 重建等） | — |
| `mimei rebackup <mid>` | 修复备份错误 | — |
| `mimei publish <mid>` | 发布到 P2P 网络 | — |
| `mimei findprovs <mid>` | 查找提供者节点 | — |
| `mimei provide <mid>` | 宣告提供此 MiMei | — |
| `mimei setright <mid>` | 设置权限 | — |
| `mimei setdomain <mid>` | 设置域名 | — |

#### mimei diagnose — 健康检查

```bash
# 本地诊断
Leither mimei diagnose <mid>

# 远程诊断（跨节点对比）
Leither mimei diagnose <mid> -n <node>

# 诊断 + 修复
Leither mimei diagnose <mid> --repair
```

#### mimei repair — 修复

```bash
# 修复 MAC 不一致
Leither mimei repair <mid>

# 试运行（只诊断不修复）
Leither mimei repair <mid> --mode=dry-run
```

#### mimei sync — 跨节点同步

```bash
Leither mimei sync <mid>
```

---

## 6. 系统命令

| 命令 | 功能 | --json |
|------|------|:--:|
| `run` | 启动 Leither 服务（`-d` 后台） | — |
| `stop` | 停止 Leither 服务 | — |
| `version` | 显示版本、架构、API 版本 | ✓ |
| `getvar <name>` | 查询系统变量 | ✓ |
| `update` | 更新到最新版本 | — |
| `stat ledger` | 账本统计 | — |
| `stat mimei` | MiMei 统计 | — |
| `stat user` | 用户统计 | — |
| `notify` | 发送邮件通知 | — |
| `init` | 初始化服务配置 | — |
| `mcp` | MCP 协议工具集 | — |

#### getvar — 查询系统变量

```bash
Leither getvar ver       # 版本号
Leither getvar health    # 健康状态
Leither getvar cpu       # CPU 信息
Leither getvar disk      # 磁盘信息
```

HTTP 等价调用：

```bash
curl http://127.0.0.1:4800/getvar?name=ver
# → "V0.23.65"
```

---

## Agent 验证脚本

Agent 执行以下序列，验证核心功能（在真实节点上已全部通过，V0.23.65）：

```bash
# 安装
curl -fsSL http://vzhan.cn/install.sh | bash
cd ~/vzhan && ./Leither run -d

# 网络
Leither swarm peers --json
# → exit_code: 0, peers.count > 0

# 文件
Leither files ls
# → MFS 根目录列表

# 应用
Leither lapp showapp --json
# → exit_code: 0, apps 列表

# 身份
Leither lpki genkey -o test.key
# → 生成 test.key 文件

# 存储
Leither mimei diagnose <mid>
# → 健康检查报告

# 系统
Leither getvar ver
# → "V0.23.65"
```

全部通过 = 节点功能验证完成。更多命令见 [doc.html](doc.html) 完整参考。