# byk

byk 是一个**别名执行器**：把常用命令写进 `*.byk.json`，用短名字调用它们。

它只做两件事——**找到别名，执行命令**。

## 安装

```bash
# PyPI
pip install byk

# 或安装脚本（macOS / Linux）
curl -fsSL https://cli.fcbyk.com/install.sh | bash
```

安装脚本会顺带把 byk 加入 `PATH`，并写入一行 shell 补全。

## 快速开始

写一个别名文件：

```json title="hello.byk.json"
{
  "hello": "echo hello world"
}
```

项目里这份手写最直接。想放进全局目录 `~/.byk/alias/` 时不必开编辑器：`byk @@hello..init` 建文件，`byk @@hello..set hello --cmd "echo hello world"` 加条目。详见[文件命令](/zh/cli/file-commands.md)。

执行：

```bash
byk hello
```

当前目录里的 `*.byk.json` 默认参与合并，而且优先级高于全局目录——`cd` 进项目就能直接调用，不用写任何声明。

需要精确指定「哪个文件里的哪个别名」时，用 `@文件.key`（本地）或 `@@文件.key`（全局）：

```bash
byk @hello.hello
```

如果某段别名只想被精确调用、不要出现在 `byk <key>` 里，在对应位置写 `"$private": true`。详见 [别名配置 - 可见性](/zh/cli/alias/config.md#可见性)。

## 一个命令是怎么执行的

1. `byk` 解析参数，识别选项与隐藏接口 `__api__`
2. 剩下第一个词作为别名名，其余作为参数
3. 命中 `@文件.key` 精确语法 → 直接读该文件
4. 否则在合并后的别名空间里查找（全局 `~/.byk/alias/` + 当前目录）
5. 替换变量（`${byk_dir}` / `${file_dir}` / `${deps_dir}` 与 `$var`），解析参数占位符
6. 在 `$cwd` 下执行命令；未命中则列出候选并退出 1

## 接下来的阅读顺序

* [选项与命令](/zh/cli/commands.md) — `-h` / `-v` / `--paths` / `--check`、执行形式与保留字
* [文件命令](/zh/cli/file-commands.md) — 每个别名文件自带的 `..init` / `..set` / `..clone`，改文件本身用它
* [程序接口](/zh/cli/api.md) — 隐藏的 `byk __api__`：写脚本、写插件时读这页
* [快速开始](/zh/cli/alias/start.md) — 三分钟写出第一个别名文件
* [别名配置](/zh/cli/alias/config.md) — 字段、继承、优先级、精确执行
* [参数处理](/zh/cli/alias/placeholders.md) — 占位符与参数消耗规则

***

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