For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/index.md.
  • English
  • byk

    byk is an alias executor: write the commands you use often into *.byk.json, then call them by short names.

    It does exactly two things — find the alias, run the command.

    Installation

    # PyPI
    pip install byk
    
    # or the install script (macOS / Linux)
    curl -fsSL https://cli.fcbyk.com/install.sh | bash

    The install script also adds byk to your PATH and writes a single line of shell completion.

    Quick Start

    Write an alias file:

    hello.byk.json
    {
      "hello": "echo hello world"
    }

    The copy in your project is quickest to hand-write. For the global directory ~/.byk/alias/ there is no editor to open: byk @@hello..init creates the file, then byk @@hello..set hello --cmd "echo hello world" adds the entry. See File Commands.

    Run it:

    byk hello

    *.byk.json files in the current directory are merged in by default, with higher priority than the global directory — cd into a project and its aliases just work, no declaration required.

    When you need to target "which alias in which file" precisely, use @file.key (local) or @@file.key (global):

    byk @hello.hello

    If a subtree should only ever be invoked explicitly and never appear under byk <key>, add "$private": true there. See Alias Configuration - Visibility.

    How a Command Runs

    1. byk parses the arguments, recognizing options and the hidden __api__ interface
    2. The first remaining word is the alias name; everything after it is passed as arguments
    3. A @file.key exact match reads that file directly
    4. Otherwise the alias is looked up in the merged alias space (global ~/.byk/alias/ + current directory)
    5. Variables (${byk_dir} / ${file_dir} / ${deps_dir} and $var) are substituted, then argument placeholders are resolved
    6. The command executes under $cwd; on a miss, candidates are listed and byk exits 1
    • Options & Commands — -h / -v / --paths / --check, execution forms, and the reserved words
    • File Commands — the built-in ..init / ..set / ..clone that edit an alias file itself
    • Program Interface — the hidden byk __api__: the page to read when writing a script or a plugin
    • Quick Start — write your first alias file in three minutes
    • Alias Configuration — fields, inheritance, priority, exact execution
    • Placeholders — placeholder syntax and argument consumption rules