For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/cli/commands.md.
  • 简体中文
  • 选项与命令

    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 取版本号。

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

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

    --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 会变成:

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

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

    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)组成,同名时项目里的覆盖全局的。

    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 结束。$ 开头的段是保留字段或自定义元数据,永远不会被当作别名执行。

    每个别名文件还带一组保留的文件命令:用 @文件..命令 / @@文件..命令 创建、编辑、克隆、安装依赖和查看文件本身。完整列表见 文件命令。

    程序接口 __api__

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

    byk __api__              # 接口清单(请求名别背,直接问)
    byk __api__ paths root   # 免解析地拿一个目录

    请求列表、每个字段的语义与调用示例都在 程序接口 里——集成时该读的是那一页。

    保留字

    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。