import { Steps } from '@rspress/core/theme';

# Quick Start

Write your first alias file in three minutes.

## Getting Started

<Steps>
  ### Create a Config File

  Create `run.byk.json` in your project root:

  ```json
  {
    "dev": "pnpm dev",
    "build": "pnpm build",
    "deploy": {
      "$cmd": "deploy --env {env}",
      "$mode": "interactive"
    }
  }
  ```

  ### Run It Directly

  ```bash
  byk dev
  byk build
  byk deploy            # interactive: asks for env first, confirms, then runs
  ```

  `*.byk.json` files in the current directory are merged in by default at priority 1 (the global directory is 0). So short names work the moment you enter the directory, and project aliases override global ones with the same name — that is "near-first".

  ### Keep It Out of the Directory

  Some files belong to a single script and shouldn't show up under `byk <key>`. Add `$private: true`:

  ```json title="run.byk.json"
  {
    "$private": true,
    "dev": "pnpm dev"
  }
  ```

  ```bash
  byk dev            # not found
  byk @run.dev       # exact invocation — the only way to call it
  ```

  ### Make It Available in Your Home Directory

  ```bash
  byk @@run..clone @run     # copy ./run.byk.json into ~/.byk/alias/
  byk dev
  ```

  A plain `cp run.byk.json ~/.byk/alias/` works too. Files under `~/.byk/alias/` default to priority `0` and are available in any directory; when you enter a project with a same-named alias, the project's copy overrides it.

  ### Going Further

  * [Alias Configuration](/cli/alias/config.md) — fields, inheritance, priority, exact execution
  * [Placeholders](/cli/alias/placeholders.md) — placeholder syntax and argument consumption rules
  * [Options & Commands](/cli/commands.md) — `-h` / `-v` / `--paths` / `--check`
  * [File Commands](/cli/file-commands.md) — the built-in commands that edit an alias file itself
  * [Program Interface](/cli/api.md) — `byk __api__`, for scripts and plugins
</Steps>

***

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