# 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](#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

| Option | Description |
|--------|-------------|
| `-h, --help` | Help: banner + Usage + Options + aliases in the merged space |
| `-v, --version` | Version, build info, and install path |
| `--paths` | Print CLI directories and alias files |
| `--check` | Check 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`.

```bash title="-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.

```bash title="--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:

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

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

```text
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

| Form | Description |
|------|-------------|
| `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.

```bash
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](/cli/file-commands.md).

## 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`.

```bash
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](/cli/api.md) — 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:

| Reserved | Why |
|----------|-----|
| `-h` / `--help` | Option |
| `-v` / `--version` | Option |
| `--paths` | Option |
| `--check` | Option |
| `__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.

***

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