# 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

```bash
# 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:

```json title="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](/cli/file-commands.md).

Run it:

```bash
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):

```bash
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](/cli/alias/config.md#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

## Where to Read Next

* [Options & Commands](/cli/commands.md) — `-h` / `-v` / `--paths` / `--check`, execution forms, and the reserved words
* [File Commands](/cli/file-commands.md) — the built-in `..init` / `..set` / `..clone` that edit an alias file itself
* [Program Interface](/cli/api.md) — the hidden `byk __api__`: the page to read when writing a script or a plugin
* [Quick Start](/cli/alias/start.md) — write your first alias file in three minutes
* [Alias Configuration](/cli/alias/config.md) — fields, inheritance, priority, exact execution
* [Placeholders](/cli/alias/placeholders.md) — placeholder syntax and argument consumption rules

***

byk v0.8.2 · this page may lag behind HEAD; `byk __api__` and `byk -v` are authoritative.
