---
url: /getting-started/cli.md
description: mayami 全部子命令、参数与退出状态
---

# 命令行

## 全局参数

```text
mayami [-c FILE] [-D DIR] [--color auto|always|never] [COMMAND]
```

| 参数 | 含义 |
|---|---|
| `-c, --config FILE` | 配置文件；环境变量 `MAYAMI_CONFIG` |
| `-D, --data DIR` | 相对路径和数据目录；环境变量 `MAYAMI_DATA` |
| `--color WHEN` | `auto`、`always` 或 `never`，默认 `auto` |
| `--version` | 打印版本、目标平台、Chromium、cronet 和 BoringSSL 状态 |
| `--help` | 打印命令帮助 |

没有子命令时默认执行 `run`。

## run

```text
mayami run [--log LEVEL]
```

读取配置并运行。`--log` 临时覆盖配置中的级别：`error`、`warn`、`info`、`debug` 或 `trace`。

## check

```text
mayami check
```

读取配置、规则集和所有能离线构建的对象，输出摘要或第一处错误。它不监听端口，不接管流量，也不创建 cache 文件。

## route

```text
mayami route HOST[:PORT]
  [--udp]
  [--protocol PROTOCOL]
  [--from ADDRESS[:PORT]]
  [--inbound NAME]
  [--process PATH]
  [--address ADDRESS]
```

按当前配置决定一条流会命中哪个规则、走哪个出站。

* 目标端口省略时是 `443`。
* `--protocol` 可取 `http`、`tls`、`quic`、`dns`、`stun`、`dtls`、`ssh`、`bittorrent`、`ntp`、`rdp`。
* `--from` 默认 `192.168.1.100:50000`。
* 域名默认假定一个 FakeIP 地址，除非用 `--address` 给出真实地址。
* 需要进程事实的规则只有在给 `--process` 时才能判断。

## init

```text
mayami init [router|segment|network]
  [-o, --output FILE]
  [--force]
```

* 模板默认是 `router`。
* 没有 `-o` 时，使用 `-c` 指向的文件；也没有 `-c` 时写 `./mayami.yaml`。
* `-o -` 写到标准输出。
* 目标已存在时必须有 `--force`。

## generate

### 控制 API 密钥

```sh
mayami generate secret
```

输出 16 字节系统随机数的十六进制形式。

### Shadowsocks 密钥

```text
mayami generate shadowsocks [METHOD]
```

默认 `2022-blake3-aes-128-gcm`。支持的方法是：

* `2022-blake3-aes-256-gcm`
* `2022-blake3-chacha20-poly1305`
* `aes-128-gcm`
* `aes-256-gcm`
* `chacha20-ietf-poly1305`
* `none`

### REALITY

```sh
mayami generate reality
```

分别输出服务器 `private_key`、客户端 `public_key` 和八字节 `short_id`。

### Kotodama

```text
mayami generate kotodama \
  --cover label=outer_sni=path \
  [--cover label=outer_sni=path ...] \
  [--master-password PASSWORD]
```

第一个 cover 是顶层 cover。输出服务端 `kotodama:` 配置块和给客户端的 `public_bundle`。

## api

```text
mayami api [--at ADDRESS] [--secret SECRET] COMMAND
```

默认从配置的 `api.listen` 连接；`--at` 可脱离配置文件直接指定地址。密钥也可用 `MAYAMI_SECRET`。

### status

```sh
mayami api status
```

输出版本、连接数、累计上下行和内存。

### outbounds

```sh
mayami api outbounds
```

按配置顺序列组、当前成员和最近一次延迟。

### select

```text
mayami api select GROUP OUTBOUND
```

切换 selector，并写入持久选择。

### test

```text
mayami api test OUTBOUND
  [--url URL]
  [--timeout MILLISECONDS]
```

默认 URL 是 `https://www.gstatic.com/generate_204`，超时 `5000` 毫秒。组会测试每个成员。

### connections

```sh
mayami api connections
```

列出正在承载的连接、目标、链、命中的规则和流量。

### close

```text
mayami api close ID|all
```

关闭一条连接或全部连接。

### logs

```text
mayami api logs [--level debug|info|warning|error]
```

流式读取日志，默认 `info`，直到中断。

### reload

```sh
mayami api reload
```

通过控制 API 触发配置重读。

## rset

### compile

```text
mayami rset compile SOURCE [-o OUTPUT]
```

读取 sing-box JSON 规则集并写出二进制 `.srs`。未指定输出时，用源文件名把扩展名改成 `.srs`。

### match

```text
mayami rset match SET TARGET
```

`SET` 可以是 mayami 读取的规则集格式；`TARGET` 是名字或地址，必要时可带端口。命中退出 0，不命中退出 1，错误退出 2。

## fetch

```text
mayami fetch URL [--via OUTBOUND] [-o, --output FILE]
```

按配置的 DNS、TLS 和出站抓取一个 URL。`--via` 省略时走 `route.final`；`-o` 省略时写标准输出。

## cache

```text
mayami cache [NAMESPACE]
```

从配置 `cache_file` 的只读副本列出各命名空间的条数，或展开一个命名空间。配置关闭缓存时返回非零。

## link

```text
mayami link [NAME] [--server HOST]
```

* 不写 `NAME` 时列出所有能生成分享链接的出站。
* 写 `NAME` 时只列出该出站或入站。
* 入站监听通配地址时，`--server` 必须给出客户端实际访问的主机。
* 一个入站有多个用户时，每个用户输出一条链接。

## bundle

```text
mayami bundle [INBOUND]
```

输出一个或全部 Kotodama 入站生成的客户端 bundle。

## completion

```text
mayami completion SHELL
```

为支持的 shell 生成补全脚本。

## 退出状态

| 状态 | 常见含义 |
|---|---|
| `0` | 成功；`rset match` 命中 |
| `1` | `rset match` 不命中；部分读取、抓取或 API 操作失败 |
| `2` | 参数、配置或构建错误 |

::: info 没有 `mayami version` 子命令
版本用全局参数 `mayami --version` 查看。旧文档里的 `mayami version` 与现行 clap 定义不一致。
:::