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/commands.md.
  • English
  • Options & Commands

    byk's command line has only four layers: options, aliases, file commands, and the program interface. Apart from the words in Reserved Words, every word is treated as an alias to look up — so you can name aliases whatever you like.

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

    Options

    OptionDescription
    -h, --helpHelp: banner + Usage + Options + aliases in the merged space
    -v, --versionVersion, build info, and install path
    --pathsPrint CLI directories and alias files
    --checkCheck alias files and report scan problems per file

    Running byk with no arguments produces exactly the same output as byk -h. The first line is always byk <version> (<commit> <build date>) [<platform>], so you can safely grab the version with byk -v | head -1.

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

    When the executable is a symlink, the installed at line gets a -> target suffix, so you can tell which copy actually runs.

    --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 is byk's home directory, Alias is where global alias files live, and Workdir is the current directory scanned for local files. Drop *.byk.json files into either directory and they join the lookup space.

    --paths also lists the top-level alias files in the global alias directory and the current working directory, one group per source. The @@ / @ key prefix tells global from local. File names are validated, but contents are not parsed: a file with broken JSON still appears here, and so do $private files and broken symlinks. Use --check to find content problems. Empty groups are omitted, including their separator.

    The alias list in the help page covers the merged space only: aliases marked $private: true never appear, since they are reachable through @file.key alone. An alias with a $cwd gets its effective directory appended, as in deploy deploy.sh (/Users/me/proj).

    Diagnostics --check

    Problems found while scanning alias files are no longer printed during normal execution. When there are any, the -h banner becomes:

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

    Use byk --check for a per-file report:

    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

    With no problems it prints Scanned N alias files; no problems. and exits 0; otherwise it exits 1. Scanned counts the candidate *.byk.json entries encountered, including invalid file names and broken symlinks. It currently covers file reading, JSON parsing, root type, alias and metadata field types, link files, invalid file names, broken symlinks, $mode, $var, and the $deps declaration (including base, target collisions, and package entries). It only looks at configuration: whether dependencies are installed is runtime state, reported by ..deps status. --check takes no alias argument — anything extra fails with check takes no arguments.

    Running Aliases

    FormDescription
    byk <key> [args...]Look up and run from the merged alias space
    byk @file.key [args...]Run an alias from a specific file in the current directory
    byk @@file.key [args...]Run an alias from a specific file in the global directory ~/.byk/alias/

    The merged space consists of the global directory ~/.byk/alias/ (priority 0) and the current directory (priority 1); on name collisions, the project's alias wins.

    byk dev                  # merged-space lookup (project takes priority)
    byk @run.build           # build from ./run.byk.json
    byk @@work.deploy        # deploy from ~/.byk/alias/work.byk.json

    The exact syntax is pure file routing with no fallback:

    • missing file → Alias file not found: @run (@@run for the global side)
    • file exists but cannot be loaded → Alias file cannot be loaded: @run, with the reason and a byk --check hint
    • missing key → Alias key not found in file @run: build
    • a path segment starts with $ → Not an alias (reserved $ field): @run.build.$cmd

    All of them exit with code 1. A $-prefixed segment is a reserved field or custom metadata and is never executed as an alias.

    Every alias file also has a set of reserved file commands: @file..command / @@file..command create, edit, clone, install dependencies for, and inspect the file itself. See File Commands.

    The __api__ Program Interface

    byk __api__ is a read-only interface for programs and editor plugins: it never executes an alias and never writes to disk, so you can call it as often as you like. It does not appear in -h.

    byk __api__              # interface manifest (don't memorise request names)
    byk __api__ paths root   # one directory, unparsed

    The request list, the meaning of every field and worked examples live in Program Interface — that is the page to read when integrating.

    Reserved Words

    Every word after byk is treated as an alias, with only these exceptions — none of them can be an alias name:

    ReservedWhy
    -h / --helpOption
    -v / --versionOption
    --pathsOption
    --checkOption
    __api__Hidden interface

    Everything else is free — even words like version or paths work as aliases, as long as they do not start with -.

    Match Order

    When you run byk <word> ..., the following order applies — the first match wins:

    1. The __api__ hidden interface
    2. Options such as -h / -v / --paths / --check
    3. @file.key / @@file.key exact execution
    4. Aliases in the merged space

    File commands are handled right before step 3: an @file..command token with .. never reaches alias lookup. When several options are given at once, -h wins, followed by --check, --paths, and -v.

    When nothing matches, byk prints Unrecognized command or alias: <word> along with candidate suggestions and exits with code 1.