import { Tab, Tabs } from '@rspress/core/theme';

# Alias Configuration

## Type Definitions

```ts title="alias.types.ts"
// Alias object (the metadata-carrying form)
type AliasObject = {
  $cmd?: string;
  $cwd?: string;
  $mode?: 'normal' | 'interactive' | 'silent';
  $description?: string;
  $recursive?: boolean;
  $private?: boolean;
  $clone?: boolean;
  [key: string]: string | AliasObject | boolean | undefined;
}

// File-level dependency declaration: assets, pip packages, npm packages
type Deps = {
  base?: string;
  files?: Array<string | { src: string; to?: string; name?: string; extract?: boolean; exec?: boolean }>;
  pip?: string[];
  npm?: string[];
};

// A single *.byk.json file: an alias object, or a one-entry link array
type AliasFileJSON =
  | {
      $priority?: number;      // ordering priority; defaults to 1 in the current directory, 0 globally; negatives become 0
      $cwd?: string;           // file- or group-level working directory, inherited by child aliases
      $mode?: 'normal' | 'interactive' | 'silent';  // file- or group-level mode, inherited by child aliases
      $private?: boolean;      // file- or group-level visibility, inherited by child aliases; private aliases stay out of the merged space
      $clone?: boolean;        // file- or group-level copy tag, inherited by child aliases; false keeps a subtree out of ..clone copies
      $paths?: string[];       // file-level PATH directories, inherited by child aliases
      $deps?: Deps;            // file-level dependencies: assets, pip packages, npm packages
      $var?: Record<string, string | Record<string, string>>;  // file-level variables
      [key: string]: string | AliasObject | Deps | number | boolean | undefined;
    }
  | [string];  // single link: an array holding exactly one path
```

Only these eight `$`-prefixed keys are interpreted at file level; any other `$xxx` is never treated as an alias and never joins the merged space — it is kept for other tools to store configuration. A `${xxx}` inside a string is handled by [variables](#variables), and undeclared names are passed to the shell verbatim.

## Alias Objects

### Key Naming Rules

* A key **cannot contain** `@` or `.`; violating entries are silently ignored
* Chinese key names are supported
* Nested groups (objects) are supported and accessed with the `.` separator

```json title="chinese-keys.byk.json"
{
  "开发": {
    "测试": "pytest -q",
    "构建": "pnpm run build"
  }
}
```

```bash
byk 开发.测试
```

### System Fields

| Field | Type | Description |
|-------|------|-------------|
| `$cmd` | string | The command to execute |
| `$cwd` | string | Working directory (inheritable) |
| `$mode` | `'normal'` | `'interactive'` | `'silent'` | How to run the alias (inheritable), defaults to `normal` |
| `$description` | string | Help-page description text (not inheritable) |
| `$recursive` | boolean | Allow re-entering this alias on the call chain (not inheritable), defaults to `false` — see [Recursion Guard](#recursion-guard) |
| `$private` | boolean | Keep this subtree out of the merged space, reachable only through exact calls (inheritable), defaults to `false` — see [Visibility](#visibility) |
| `$clone` | boolean | Keep this subtree out of `..clone` copies (inheritable), defaults to `true` — see [Cloning](#cloning) |

:::note
An object containing `$cmd` is an alias leaf node. An object with only `$cwd` / `$mode` / `$private` / `$clone` but no `$cmd` is a **group with inherited properties** and is not executable itself.
:::

### Working Directory (cwd)

Three levels of inheritance: file → group → alias, with the level closer to the alias winning. `~` expands, and **a relative path is resolved against the alias file's directory** — not the directory you happened to run `byk` from. With no `$cwd` at all, the alias runs in the invocation directory.

<Tabs>
  <Tab label="Alias level">
    ```json
    {
      "install": {
        "$cmd": "npm i",
        "$cwd": "/project/web"
      }
    }
    ```
  </Tab>

  <Tab label="Group level">
    ```json
    {
      "services": {
        "$cwd": "/project",
        "install": "npm i",
        "web": {
          "$cwd": "/project/web",
          "dev": "pnpm dev",
          "build": "pnpm build"
        }
      }
    }
    ```

    `install` inherits `/project` from `services`, while `web.dev` and `web.build` use the `/project/web` override from the `web` group.
  </Tab>

  <Tab label="File level">
    ```json
    {
      "$cwd": "/project/web",
      "install": "npm i",
      "start": {
        "$cmd": "pnpm dev",
        "$cwd": "/project/web/frontend"
      }
    }
    ```

    `install` inherits the file-level `/project/web`, while `start` uses its own `/project/web/frontend`.
  </Tab>
</Tabs>

A file-level `$cwd` is inherited by every child alias. If one alias needs to return to the directory where you typed `byk`, set its `$cwd` to `"${work_dir}"`:

```json
{
  "$cwd": "/project/web",
  "here": { "$cmd": "pwd", "$cwd": "${work_dir}" }
}
```

`${work_dir}` is substituted during the scan phase as an absolute path, so writing it is equivalent to writing that absolute path directly and it no longer takes part in relative-path resolution. It is the directory in which the current `byk` process started: when alias A calls `byk B` from its own `$cwd`, B sees A's working directory as `${work_dir}`.

### Execution Mode

`$mode` decides how an alias runs. The three states are mutually exclusive and `normal` is the default.

| Value | Behavior |
|---|---|
| `normal` | Print the hint lines, then run directly |
| `interactive` | Print the hint lines, ask for each placeholder, then wait for Enter |
| `silent` | Say nothing even on a terminal (a pipe already gets nothing) |

Before running, byk prints two lines to **stderr**: the source (`file.key` plus the working directory) and the resolved command. They belong there because they are commentary for a human, not data to be piped:

* `byk build > log.txt` and `byk build | grep error` receive only the command's own output;
* when stderr is not a terminal (redirected with `2>`, CI, editor tasks) the two lines are skipped entirely;
* `$mode: "silent"` is for staying quiet on a terminal as well.

```bash
byk build
# > @.build /project
#
# > pnpm build
#
# ...(output of pnpm)

# with "$mode": "silent"
byk build
# ...(output of pnpm only)
```

`interactive` fits commands with side effects:

```bash
byk deploy
# ~ deploy --env {env} --tag {version}
#   env: staging
#   version: v2.0
# ~ deploy --env staging --tag v2.0     ← bold green
#    Press Enter to execute...
```

`$mode` inherits through three levels — file, group, alias — with the closest one winning.

<Tabs>
  <Tab label="Alias level">
    ```json
    {
      "deploy": {
        "$cmd": "deploy --env {env} --tag {version}",
        "$mode": "interactive"
      }
    }
    ```
  </Tab>

  <Tab label="Group level">
    ```json
    {
      "danger": {
        "$mode": "interactive",
        "drop": "rm -rf {path}",
        "backup": {
          "$cmd": "rsync -a ./ {dest}",
          "$mode": "silent"
        }
      }
    }
    ```

    `drop` inherits the interactive mode from `danger`; `backup` just says `silent` — there is no second switch to turn off.
  </Tab>

  <Tab label="File level">
    ```json
    {
      "$mode": "silent",
      "build": "pnpm build",
      "deploy": {
        "$cmd": "deploy --env {env}",
        "$mode": "interactive"
      }
    }
    ```

    The whole file stays quiet; only `deploy` asks for confirmation.
  </Tab>
</Tabs>

:::note
Interactive and silent are the two extremes of one axis: interactive has to show what is about to run, so `silent` merely keeps byk quiet — it never skips a confirmation step. Reach for `interactive` when a command needs one.
:::

### Recursion Guard

`$cmd` is an arbitrary shell string, so it can invoke byk again — including resolving back to itself. Give the `add` alias a `$cmd` of `byk add` and every level re-expands the same alias; each level is its own process, so there is no stack to overflow, only a process count that keeps climbing until the machine gives up.

byk therefore leaves a trail on the call chain: before running an alias it pushes `file.key` onto the `BYK_ALIAS_STACK` environment variable (comma-separated) and hands it to the child process. A level that finds itself already on the chain reports and exits:

```text
Error: alias recursion detected: @dev.build -> @dev.release -> @dev.build
```

The **whole chain** is printed, not just the endpoints — which level looped back is the thing worth locating. Chains deeper than 32 levels are stopped as well: that backstop exists for wrappers that scrub the environment (`env -i byk build`), where the trail cannot survive and depth is all that is left.

Deliberate self-invocation (`FOO=1 byk build`, `sudo byk serve`) needs an explicit opt-in; these two are equivalent:

```json
{
  "build": {
    "$cmd": "FOO=1 byk build",
    "$recursive": true
  }
}
```

```bash
BYK_ALLOW_RECURSION=1 byk build   # temporary, global
```

Opting in only disables the "same alias re-entered" check; the depth limit still applies.

:::note
`$recursive` applies to the current alias only and is not inherited. `$mode: "silent"` does not suppress this error either — explaining why a command hung is exactly what it is for.
:::

### Description Text

`$description` replaces the command text shown by default in the help page. It applies to the current alias only and is not inherited.

```json
{
  "release": {
    "$mode": "interactive",
    "$cmd": "cz bump {version}",
    "$description": "Bump the version interactively"
  }
}
```

```text title="byk -h excerpt"
Aliases:
  release    Bump the version interactively
```

When unset, the command itself is shown:

```text
Aliases:
  release    cz bump {version}
```

A resolved `$cwd` is appended in parentheses only when no description is set — with a description, the line stays a single summary and the working directory is left out.

### PATH Directories

`$paths` prepends directories to `PATH` before an alias runs, letting the alias call executables in those directories directly.

**File level only** — all child aliases inherit it; writing it inside a group is ignored.

```json title="run.byk.json"
{
  "$paths": ["./scripts", "~/tools/bin"],
  "deploy": "deploy.sh",
  "check": "lint.sh"
}
```

* Relative paths are resolved against the directory containing the config file, and `~` expands
* **Nonexistent directories are silently skipped** — they never reach the child process's `PATH`
* Separately, byk always prepends the working directory's `node_modules/.bin`; when the file declares `$deps.pip` / `$deps.npm`, the dependency directory's venv bin / `node_modules/.bin` is prepended as well — no need to write either into `$paths` yourself
* The order of `$paths` is the order in `PATH`, so earlier entries win

### Dependencies

`$deps` declares what an alias file needs — asset files plus optional pip and npm packages — and byk installs them into that file's dedicated directory:

| File | Dedicated directory |
|------|---------------------|
| Global `~/.byk/alias/hello.byk.json` | `~/.byk/deps/@@hello/` |
| Local `./hello.byk.json` | `./.byk/deps/@hello/` |

Both scopes follow the same rules, only the root differs: global dependencies stay under `~/.byk`, local ones travel with the project (delete the project, delete its dependencies — no global clutter). A local install writes `.byk/deps/.gitignore` containing `*`, so downloaded assets never show up in `git status`.

The declaration itself never touches the network — installing is an explicit verb:

```bash
byk @@tool..deps install      # fetch files and install declared packages
byk @@tool..deps status       # declared, present, missing, stale
byk @@tool..deps uninstall    # delete the whole dedicated directory
byk @@tool..clone <source> -d # or install them right after cloning
```

```json title="~/.byk/alias/tool.byk.json"
{
  "$deps": {
    "base": "https://example.com/releases/v1/",
    "files": [
      "tool-1.4.tar.gz",
      { "src": "cli-linux", "to": "bin", "exec": true },
      { "src": "../shared/config.json", "name": "tool.cfg", "to": "etc" },
      "https://cdn.example.com/elsewhere.bin"
    ],
    "pip": ["requests", "click>=8.0"],
    "npm": ["chalk", "@scope/pkg@^1.2"]
  },
  "$paths": ["${deps_dir}/bin"],
  "run": { "$cmd": "tool --version" }
}
```

| Rule | Description |
|------|-------------|
| String shorthand | Equals `{ "src": "..." }`; the file name is derived from the last segment of the address |
| `base` | The resolution base for relative `src`, as a **directory**. On disk it must be absolute: a remote clone writes an absolute http(s) URL, a local clone writes a local absolute path. **You normally do not write this by hand** — `..clone` records it for you. A hand-written value must be a literal: an absolute URL, an absolute path, or a relative form that `..clone` will interpret (`.`, `../`, `sub/dir`). Variables are not supported |
| `src` | An absolute http(s) URL, or a path relative to `base` (`./x`, `../x`, `bin/tool`); variables are expanded before validation, so a value like `${url}` is fine. Absolute addresses are fetched with the system `curl`, local paths are copied directly, and a missing `curl` errors with an install hint |
| `to` | A subdirectory relative to the dedicated directory (root by default); `/` separated only, `..`, absolute paths and backslashes rejected |
| `name` | The saved file name, overriding the derived value; mutually exclusive with `extract` |
| `extract` | Extract as a tar-family archive (`tar.gz` / `tar.xz` / `tar.bz2`, compression auto-detected), delegated to the system `tar`; `to` is the target directory and the log marks the line with `(extract)`. Without `to` the archive unpacks into the dependency root, which requires it to be the only entry (reinstalling replaces the whole directory). Archive entries escaping the target directory abort the install. Mutually exclusive with `exec` |
| `exec` | Marks the downloaded file executable (no-op on Windows) |
| `pip` | Python package specs (PEP 508, e.g. `requests`, `click>=8.0`); installed into `.venv` inside the dedicated directory, created with `python3` (`python` on Windows) when missing. The venv's `bin` / `Scripts` is prepended to `PATH`. Requires Python 3 |
| `npm` | npm package specs (`chalk`, `commander@^12`, `@scope/pkg`); installed into the dedicated directory's `node_modules` with a minimal `package.json` (`byk-deps`, `private`). `node_modules/.bin` is prepended to `PATH`. Requires Node.js / npm |
| Sync (`files`) | The declaration is the desired state: missing assets are added, changed ones replaced, removed ones deleted; the manifest in `.byk-deps.json` means unchanged assets are never re-downloaded |
| Scoped removal | Only paths recorded in the manifest and no longer declared are deleted; anything else is left in place with a warning |
| Confirmation | install no longer asks twice: it prints each file / pip / npm action, then runs; `uninstall` still confirms |
| Linkage | `..rename` renames the dedicated directory along, `..destroy` deletes it, `..link` warns about a stale directory when retargeting |

**Packages install alongside file entries.** `$deps.pip` and `$deps.npm` run on every `..deps install` — pip and npm decide what is current — so `--force` only affects file entries. Neither is recorded in `.byk-deps.json`: removing a spec from the declaration does not uninstall it; `..deps uninstall` clears the whole directory instead. `..deps status` lists each package as `pip:<spec>` / `npm:<spec>`; a pip direct reference (URL or VCS) is `unknown` because there is no package name to check locally. `files` is optional, so a declaration may contain only packages.

**`base` is the only field clone rewrites.** A landed alias file lives in `~/.byk/alias/` and carries no location of its own, so relative paths can only be interpreted at clone time. The form it is frozen into depends on where the bytes came from, and that form decides how assets are fetched:

| Clone source | `base` landed on disk | How assets are fetched |
|---|---|---|
| Remote (URL, `-gh` / `-ge` / `-jd`) | Absolute http(s) directory URL | `curl` |
| Local (`@@name`, `@name`, a path) | Local absolute directory path | direct copy |

Neither side crosses into the other: **a remote clone only ever writes the URL form, so an alias file you got from the network cannot read local files.** That is not enforced by a check — the local-path form simply never reaches it.

The fill-in rules are the same for both, only the base point and the product differ: absent means the source file's directory, a relative form (`.`, `../`, `sub/dir`) is resolved against the source file, and an absolute address (URL or path) is kept as-is with only the trailing `/` added. The base point is always the **source file's** directory, never the destination directory — the relative paths in `files` were written against the source document, and those files are not sitting next to `~/.byk/alias/`.

Writing `base` back makes clone re-serialise the document (keys sorted). Files with neither `$deps` nor `$clone` are untouched and stay byte-for-byte copies; when `base` already holds the value about to be written, nothing is rewritten either, so cloning twice produces no diff. **Cloning rejects variables in `base`.** A clone has no variable table, so `"base": "${CDN}"` cannot be evaluated; guessing a value would bake a bogus address into the file, so clone fails and tells you to fix the source. (Reading is laxer: `..deps i` expands variables first, so a hand-written `${CDN}` that resolves to an absolute address still works. The restriction is about clone, and the editor schema follows the clone side.) `base` is meant to be a literal written by a program: clone freezes it once, and every later reader sees the same thing.

A local `base` is not portable: it names an absolute path on this machine and means nothing on another. Local dependencies are meant to be local development aids — do not expect a shared alias file to keep working.

On Windows there is one more rule: a `/sub`-style base has no drive letter, so Windows resolves it against the current drive and the same file points somewhere else after a `cd`. Only relative paths and drive-letter absolutes (`C:/share/`) are accepted; `/sub` fails with an error.

**Local entries are compared by the source file's mtime**: a source newer than the installed copy triggers a reinstall, so editing a local build artefact and rerunning `..deps i` takes effect (use `--force` for an unconditional rebuild). URL entries have no such notion — the same address is the same content, so `keep` is always safe. A missing source file is reported with its path instead of a quiet "up to date".

Reference the dedicated directory with `${deps_dir}`. byk owns that directory: installing syncs file entries to the declaration, so do not keep anything there that must survive an install.

`--check` only validates the declaration itself (does it parse, do two entries collide, does a relative `src` have a `base`, are package entries non-empty strings); what is missing or outdated is `..deps status`'s job.

`$var`, `$paths` and `$deps` itself all go through variable substitution first, so custom variables like `${version}` can build URLs.

A local file that wants dependencies: first create a global link with `..init --link`. The declaration travels with the target file, while the install location follows the link file's key. See [Single Link](#single-link).

### Variables

Variables come from two places and are merged into **a single table**, substituted once during the scan phase:

| Source | Description |
|--------|-------------|
| Built-in | `${byk_dir}` → `~/.byk` (the resource root, not the binary directory); `${work_dir}` → the directory `byk` was invoked from (unaffected by `$cwd`); `${file_dir}` → the directory holding the current alias file; `${deps_dir}` → that file's dependency directory: `~/.byk/deps/@@<file-name>` for global files, `<file-dir>/.byk/deps/@<file-name>` for local ones |
| `$var` declarations | File-scoped custom variables |

On a name collision, **the file declaration wins** — the value you wrote explicitly is the value you get.

The syntax is uniformly `${name}`, where `name` matches `[A-Za-z_][A-Za-z0-9_]*` (the same rule as shell identifiers):

```json title="run.byk.json"
{
  "$var": {
    "BASE": "https://github.com/owner/repo/releases/download",
    "VER": {
      "darwin-arm64": "tool-mac",
      "linux-x86_64": "tool-linux"
    }
  },
  "fetch": "curl -fsSL ${BASE}/${VER} -o /tmp/tool",
  "log": "tail -f ${byk_dir}/logs/app.log"
}
```

| Rule | Description |
|------|-------------|
| Syntax | `${name}` — the braces are the delimiter and are required |
| Bare `$xx` | Not recognized; passed to the shell as-is (`$HOME`, `$PATH` are still expanded by the shell) |
| Scope | File-level: applies to all string values including `$cmd` / `$cwd` / `$paths`; JSON keys are untouched |
| Result | Every built-in expands to an absolute path, equivalent to writing that absolute path directly in the config; `${work_dir}` can therefore go straight into `$cwd` to override an inherited value |
| Override | A `$var` entry with a built-in's name takes that built-in's place |
| Self-reference | In `"byk_dir": "${byk_dir}/tools"` the right-hand side is the built-in value, yielding `~/.byk/tools` |
| Escaping | `\${byk_dir}` is passed to the shell untouched, printing the literal `${byk_dir}` |
| Platform mapping | A value can be a platform map (`linux-x86_64` / `linux-arm64` / `darwin-x86_64` / `darwin-arm64` / `windows-x64`); the current platform's value is used |
| Cross-references | Values may reference each other regardless of declaration order, for at most 8 rounds |
| Undefined | `${XXX}` is kept as-is; `args` is reserved for placeholders and its declaration is ignored |
| Invalid names | Names that are not valid identifiers are ignored with a warning on stderr |

:::tip Why the braces are mandatory
A bare `$byk_dir` has no terminator: there is no way to tell whether `$byk_dirfoo` means the variable `byk_dirfoo` or `byk_dir` followed by `foo`. `${byk_dir}foo` has no such ambiguity — which is also why it matches the shell syntax you already know.
:::

**Quoting is your job**: when a value contains whitespace, wrap it in quotes per shell rules; byk will not do it for you.

```json title="run.byk.json"
{
  "log": "tail -f \"${byk_dir}/my logs/app.log\"",
  "where": "echo ${file_dir}"
}
```

Keep the three directories apart:

| Variable | Points at |
|----------|-----------|
| `${file_dir}` | The directory holding the alias file |
| `${work_dir}` | The directory `byk` was invoked from, unaffected by any `$cwd` inheritance |
| `$cwd` / `$PWD` | The directory the command actually runs in |

Do not use the shell's `$PWD` to find the invocation directory: byk starts the shell with `$cwd` as its working directory, so `$PWD` is reset to `$cwd` and can never see the invocation directory. Windows' `%CD%` behaves the same way. Use `${work_dir}` instead.

### Usage Examples

<Tabs>
  <Tab label="System fields">
    ```json
    {
      "dev": "vite",

      "install": {
        "$cmd": "npm i",
        "$cwd": "/Users/me/project/web"
      },

      "deploy": {
        "$cmd": "deploy --env {env}",
        "$mode": "interactive"
      }
    }
    ```

    ```bash
    byk install          # runs npm i in /Users/me/project/web
    ```
  </Tab>

  <Tab label="Nested groups">
    ```json
    {
      "dev": {
        "test": "pytest -q",
        "build": {
          "$cmd": "pnpm run build",
          "web": "pnpm run build:web",
          "api": "python -m build"
        }
      },
      "clean": "find . -type d -name __pycache__ -exec rm -rf {} +"
    }
    ```

    ```bash
    byk dev.test          # pytest -q
    byk dev.build         # pnpm run build
    byk dev.build.web     # pnpm run build:web
    byk clean             # find ...
    ```
  </Tab>
</Tabs>

## Alias Files

byk reads two locations: the **global directory** `~/.byk/alias/` and the **current working directory** (non-recursive).

### File Naming

| Format | Example | Description |
|--------|---------|-------------|
| `[name].byk.json` | `run.byk.json` | Recommended form; the name is the file key |
| `.byk.json` | `.byk.json` | Anonymous form; the key is an empty string |

:::warning
**Legal characters**: letters, digits, `-`, `_`, and Chinese characters.

**Forbidden characters**: `.`, `@`, `/`, and spaces.

Illegally named files (such as `aaa.bbb.byk.json`) are **silently skipped** — no error is raised.
:::

### Directory Layout

```tree
# global
~/.byk/alias/
├── alias.byk.json
├── work.byk.json
└── .byk.json
```

```tree
# current directory
./
├── run.byk.json
├── release.byk.json
└── .byk.json
```

### Single Link

When the root is an **array holding one path**, the file is a link file: a pointer to another alias file:

```json title="~/.byk/alias/ops.byk.json"
["~/proj/web/run.byk.json"]
```

The link file gives up its own identity: the `@` / `@@` prefix, its key and its default priority stay with the link file, while the aliases and every declaration come from the target — and relative paths resolve against the **target's** directory. The same bundle therefore behaves identically whether it is scanned directly or reached through a link.

```json title="~/proj/web/run.byk.json"
{
  "$cwd": ".",
  "build": "node build.js",
  "deploy": "node deploy.js"
}
```

```bash
byk build           # runs node build.js inside ~/proj/web
byk @@ops.build     # exact call goes through the link's key
```

| Rule | Behavior |
|---|---|
| One entry only | Extra entries are ignored with a note on stderr; the first is used |
| Path base | Relative paths resolve against the **link file's** directory; `~` and `${...}` work |
| One level | The target may not itself be an array; that is an error and the file is skipped |
| Identity | Key, `@` / `@@` prefix and default priority come from the link; everything else from the target |
| `$private` | Still honoured: a target with `true` pulls the link out of the merged namespace, leaving exact calls only |
| Dependencies | `$deps` declared in the target works as usual; the install location follows the link file's key: `~/.byk/deps/@@<link-file-name>` for a global link, `<link-dir>/.byk/deps/@<link-file-name>` for a local one |

:::note
A missing target, broken JSON or an empty array only skips that one file — other aliases keep working.
:::

### Priority

All merged files share a single key space, and higher-priority files override lower-priority ones.

#### Defaults

| File location | Default priority |
|---------------|------------------|
| Current directory `[name].byk.json` | 1 |
| Current directory `.byk.json` | 1 (loads last among its peers) |
| Global `[name].byk.json` | 0 |
| Global `.byk.json` | 0 (loads last among its peers) |

Hence "near-first": project files automatically override same-named global aliases, so `byk <key>` works the moment you enter a directory — no declaration needed.

Files at the same priority load in alphabetical order by filename, and the anonymous `.byk.json` sorts **last** among its peers; later files override earlier ones. So if both `a.byk.json` and `.byk.json` in one directory define `build`, the `.byk.json` copy is the one that runs.

:::note Running inside the global directory
When the cwd happens to be `~/.byk/alias/`, the files there belong to both the "current directory" and the "global directory". They are scanned in both roles (`@f` and `@@f` both work), but they participate in the merge **only once, as the global role** — they are never merged twice.
:::

#### Custom Ordering

Only write a number when you need to outrank other files in the same directory:

```json title="any .byk.json"
{
  "$priority": 20,
  "build": "vite build"
}
```

`$priority` only orders same-name collisions; values below 0 are treated as 0. Whether a subtree enters the merged space is controlled by `$private`.

:::note
`$priority` is a reserved field and is never treated as an alias key. When omitted, the current directory uses 1 and the global directory uses 0.
:::

### Visibility

`$private: true` keeps a subtree **out of the merged space**; it stays reachable through exact syntax `@file.key` / `@@file.key`.

Like `$cwd` and `$mode`, it has three levels of inheritance: file → group → alias, with the closest level winning. A child can set `false` to expose its subtree again.

```json title="run.byk.json"
{
  "shared": "echo everyone-can-run-this",
  "scratch": {
    "$private": true,
    "deploy": "deploy --env {env}"
  }
}
```

`byk shared` still works; `byk scratch.deploy` is not found and only `byk @run.scratch.deploy` reaches it.

To keep a whole file out of the merged space, put `$private` at the file root:

```json title="local.byk.json"
{
  "$private": true,
  "deploy": "deploy --env {env}"
}
```

:::note
`$private` only affects the merged space; exact calls always work, including aliases inside a private group.
:::

### Cloning

`$clone: false` marks a subtree as personal: `..clone` never copies it. It is a copy-time tag only — it does not affect the merged space, execution, completion, or any other lookup.

Like `$private`, it has three levels of inheritance: file → group → alias, with the closest level winning. A child can set `true` to expose its subtree again.

```json title="run.byk.json"
{
  "$clone": false,
  "shared": { "$clone": true, "whoami": "whoami" },
  "deploy": "deploy --prod"
}
```

Cloning this file yields only `shared.whoami`; `deploy` is dropped. If nothing would be left, `..clone` refuses and writes no file. The tag itself never appears in the copy.

`$private` and `$clone` are independent: write both when an alias should stay out of the merged space **and** out of cloned copies.

:::note
`$clone` only governs `byk ..clone`. `cp`, git, and fetching the file by other means still see the original bytes — it is a declaration, not encryption.
:::

### Exact Execution Syntax

| Syntax | Description |
|--------|-------------|
| `byk @release.build` | `build` from `release.byk.json` in the current directory |
| `byk @@release.build` | `build` from `~/.byk/alias/release.byk.json` |
| `byk @.build` | `build` from the anonymous `.byk.json` in the current directory |
| `byk @@.build` | `build` from the anonymous `.byk.json` globally |

Conventions:

* Pure file routing, no fallback
* File not found → `Alias file not found: @release` (`@@release` on the global side)
* File exists but cannot be loaded → `Alias file cannot be loaded: @release`, with the reason and a `byk --check` hint
* File exists but key not found → `Alias key not found in file @release: build`
* A path segment starts with `$` → `Not an alias (reserved $ field)`; `$` fields are reserved or custom metadata, not aliases
* All of these exit with code 1

***

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