# 选项与命令

byk 的命令行只有四层：**选项**、**别名**、**文件命令**、**程序接口**。除了[保留字](#保留字)里的几个词，其余任何一个词都会被当作别名去查找——所以想到什么名字都能用。

```
Usage: byk [OPTIONS] [ALIAS] [ARGS]...
```

## 选项

| 选项 | 说明 |
|------|------|
| `-h, --help` | 帮助：banner + Usage + Options + 合并空间里的别名 |
| `-v, --version` | 版本、构建信息与安装路径 |
| `--paths` | 打印 CLI 目录与别名文件 |
| `--check` | 检查别名文件，按文件汇总扫描发现的问题 |

`byk` 不带参数与 `byk -h` 输出完全一致。第一行固定为 `byk <版本> (<commit> <构建日期>) [<平台>]`，可以安全地用 `byk -v | head -1` 取版本号。

```bash title="-v"
$ byk -v
byk 0.7.0 (a1b2c3d4e 2026-11-08) [darwin-arm64]
installed at /opt/homebrew/bin/byk
```

`installed at` 那行在可执行文件是符号链接时会追加 `-> 目标路径`，用来确认真正执行的是哪一份。

```bash title="--paths"
$ byk --paths

CLI Home: /Users/coke/.byk
Alias: /Users/coke/.byk/alias
Workdir: /Users/coke/proj
---------------------------
@@ops: /Users/coke/.byk/alias/ops.byk.json
---------------------------
@: /Users/coke/proj/.byk.json
@www: /Users/coke/proj/www.byk.json

```

`CLI Home` 是 byk 的家目录，`Alias` 是全局别名文件所在目录，`Workdir` 是扫描本地文件时使用的当前目录。把 `*.byk.json` 放进这两处目录，它就会进入查找空间。

`--paths` 还会列出全局别名目录和当前工作目录顶层的别名文件，每个来源一组。`@@` / `@` 前缀区分全局与本地。只校验文件名，不解析内容：JSON 损坏的文件、标了 `$private` 的文件、断链的符号链接也会出现在这里。内容问题用 `--check` 查。空分组连同分隔线一起不打印。

帮助页里的别名列表只包含**合并空间**中的别名：标了 `$private: true` 的别名不出现在这里，因为它们本来就只能通过 `@file.key` 调用。设了 `$cwd` 的别名后面会附上生效目录，形如 `deploy  deploy.sh (/Users/me/proj)`。

### 诊断 `--check`

扫描别名文件时发现的问题不再在普通执行时直接输出。只要有问题，`-h` 顶部的 banner 会变成：

```text
-----------------------------
1 alias file has problems
Run byk --check for details
-----------------------------
```

用 `byk --check` 查看按文件分组的明细：

```text
Scanned 2 alias files; 1 has problems (1 error).

/Users/me/.byk/alias/gone.byk.json
  error: cannot load link target /Users/me/.byk/alias/missing.byk.json
```

没有任何问题时输出 `Scanned N alias files; no problems.` 并返回 0；有问题返回 1。`Scanned` 统计的是遇到的候选 `*.byk.json` 目录项，包括非法文件名和断链的符号链接。目前覆盖：文件读取、JSON 解析、根类型、别名与元数据字段类型、链接文件、非法文件名、断链符号链接、`$mode`、`$var`、`$deps` 声明（含 `base`、落点冲突与包条目）等。它只查配置本身——依赖装没装是运行时状态，用 `..deps status` 看。`--check` 不带别名参数，多写会报 `check takes no arguments`。

## 执行别名

| 形式 | 说明 |
|------|-------------|
| `byk <key> [args...]` | 在合并后的别名空间里查找并执行 |
| `byk @file.key [args...]` | 精确执行**当前目录**某个文件里的别名 |
| `byk @@file.key [args...]` | 精确执行**全局目录** `~/.byk/alias/` 里某个文件的别名 |

合并空间由全局目录 `~/.byk/alias/`（优先级 0）与当前目录（优先级 1）组成，同名时项目里的覆盖全局的。

```bash
byk dev                  # 合并空间查找（项目里的优先）
byk @run.build           # ./run.byk.json 的 build
byk @@work.deploy        # ~/.byk/alias/work.byk.json 的 deploy
```

精确语法只做文件路由，不做 fallback：

* 文件不存在 → `Alias file not found: @run`（全局是 `@@run`）
* 文件存在但无法加载 → `Alias file cannot be loaded: @run`，附原因并提示 `byk --check`
* key 不存在 → `Alias key not found in file @run: build`
* 路径段以 `$` 开头 → `Not an alias (reserved $ field): @run.build.$cmd`

以上都以退出码 1 结束。`$` 开头的段是保留字段或自定义元数据，永远不会被当作别名执行。

每个别名文件还带一组保留的**文件命令**：用 `@文件..命令` / `@@文件..命令` 创建、编辑、克隆、安装依赖和查看文件本身。完整列表见 [文件命令](/zh/cli/file-commands.md)。

## 程序接口 `__api__`

`byk __api__` 是给程序和编辑器插件用的只读接口：**从不执行别名，从不写磁盘**，可以任意频率调用。它不出现在 `-h` 里。

```bash
byk __api__              # 接口清单（请求名别背，直接问）
byk __api__ paths root   # 免解析地拿一个目录
```

请求列表、每个字段的语义与调用示例都在 [程序接口](/zh/cli/api.md) 里——集成时该读的是那一页。

## 保留字

`byk <word>` 里的任何一个词都会被当作别名查找，只有下面这几个例外，别名不能同名：

| 保留 | 原因 |
|------|------|
| `-h` / `--help` | 选项 |
| `-v` / `--version` | 选项 |
| `--paths` | 选项 |
| `--check` | 选项 |
| `__api__` | 隐藏接口 |

除此之外都是自由的——连 `version`、`paths` 这样的词也能当别名，只要不带前导 `-`。

## 匹配顺序

输入 `byk <word> ...` 时按以下顺序判断，第一个命中即返回：

1. `__api__` 隐藏接口
2. `-h` / `-v` / `--paths` / `--check` 等选项
3. `@file.key` / `@@file.key` 精确执行
4. 合并空间里的别名

文件命令在步骤 3 之前就地处理：含 `..` 的 `@文件..命令` 不会走到别名查找。同时给出多个选项时，`-h` 优先，其次是 `--check`、`--paths`、`-v`。

全部未命中时，输出 `Unrecognized command or alias: <word>`，并附上候选建议，退出码 1。

***

byk v0.8.2 · 本页可能落后于 HEAD，以 `byk __api__` 与 `byk -v` 为准。
