# The `__api__` Program Interface

`byk __api__` is the machine-facing side of byk: **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` — it was never meant for people.

Three rules apply to every request:

* **stdout carries data only** — warnings and errors go to stderr, so `$(byk __api__ …)` always yields a clean value
* **failure exits 1** — unknown request, missing argument, unsupported shell, unknown path name
* **no argument slots beyond the table** — one extra argument is an error, not something silently ignored

## Requests

| Request | Output |
|---------|--------|
| `__api__ completion <shell>` | Shell registration script (zsh / bash / fish) |
| `__api__ complete [--with-descriptions] <words...>` | Completion candidates, one per line; the flag appends a tab-separated description for built-in options, file-command verbs, and file keys (their alias file path) |
| `__api__ resolve <key> [args...]` | Resolved alias, JSON |
| `__api__ paths` | CLI directories, working directory, and alias file list, JSON |
| `__api__ paths <name>` | A single bare path (`root` / `alias` / `workdir`) |
| `__api__ file <file-key>` / `--list` | Address of a single alias file, or the full file list, JSON |
| `__api__ expand [--no-builtins] <path>` | Expand variables in a JSON file, JSON output |
| `__api__ check` | Scan diagnostics, JSON |
| `__api__` (no args) | Interface manifest, JSON |

Keep the last one close: **don't memorise request names, ask for them**. The top-level `version` is the CLI version, matching the first line of `-v`, so integrations need not parse version text.

```bash
byk __api__
```

```json title="byk __api__"
{
  "version": "0.8.0",
  "requests": [
    {
      "name": "completion",
      "args": "<shell>",
      "description": "print the shell registration script (zsh|bash|fish)"
    },
    {
      "name": "complete",
      "args": "[--with-descriptions] <words...>",
      "description": "print completion candidates; the flag appends a tab-separated description"
    },
    {
      "name": "resolve",
      "args": "<key> [args...]",
      "description": "resolve an alias to its final command without executing"
    },
    {
      "name": "paths",
      "args": "[name]",
      "description": "print CLI paths and alias file locations as JSON; with <name>, print only that path (root|alias|workdir)"
    },
    {
      "name": "file",
      "args": "<file-key> | --list",
      "description": "resolve an alias file key (@name / @@name) to its path, or list every alias file with --list"
    },
    {
      "name": "expand",
      "args": "[--no-builtins] <path>",
      "description": "expand file-level $var in a JSON file without alias validation; --no-builtins leaves byk_dir/work_dir/file_dir/deps_dir unset"
    },
    {
      "name": "check",
      "args": "",
      "description": "print scan diagnostics as JSON; problems do not change the exit code"
    }
  ]
}
```

## completion `<shell>`

Prints the completion registration script for a shell, which in turn calls `complete` on Tab. An unsupported shell exits 1 and lists the three that work:

```text
Unsupported shell: pwsh
  Supported: zsh, bash, fish
```

This request exists for the install script; day to day you only need one line (see [How completion hooks up](#how-completion-hooks-up)).

## complete `[--with-descriptions] <words...>`

Hand it the words already typed on the command line and it returns candidates, one per line. With an `@` / `@@` prefix it returns file keys only; with a group prefix it returns that group's children. An empty word lists merged aliases only — file keys appear once the word starts with `@` / `@@`. With `--with-descriptions`, built-in options, file-command verbs, and file keys all carry a tab-separated description; a file key describes itself with its alias file path, home directory shown as `~`.

```bash
$ byk __api__ complete grp.
grp.inner
```

**Only aliases stop at the first word.** An alias is a single dotted token (`grp.inner`), so once a word is closed by a space everything after it is passed to the target command as-is and byk cannot know what belongs there — `complete grp ''` (Tab after `byk grp `) returns nothing instead of listing `inner` as a subcommand. When the cursor sits after a space the shell passes one empty word, and that empty word is exactly what separates "still typing the first word" from "first word already finished".

File commands are the exception: their arguments are interpreted by byk itself, so `..help` completes command names, `..remove` completes existing keys in the file, `..clone` / `..link` / `..init --link` complete source files, and a command completes its own options. The list lives in [File Commands - Completion](/cli/file-commands.md#completion).

Each call is a read-only scan, and scan-time warnings about alias files (an invalid variable name, say) still go to stderr — stdout holds candidates only, which is why the completion script can wrap it in `$(...)`.

## resolve `<key> [args...]`

Resolves an alias without running it: final command, working directory, PATH prefixes and execution mode. The key accepts either form — a name from the merged space (`dep`), or the exact syntax (`@run.build`, `@@ops.deploy`). File commands are not aliases: `@file..command` is rejected with exit code 1, and so is a path segment that starts with `$` (a reserved field or custom metadata).

:::warning Not `file.key`
`run.build` is a **dotted path**, looked up as a group name inside the merged space, and will usually miss. File keys take a prefix: `@run.build`.
:::

```bash
byk __api__ resolve @run.build --env staging
```

| Field | Meaning |
|-------|---------|
| `key` | The key you passed, echoed back |
| `source` | The file key that matched, e.g. `@run` / `@@ops` |
| `sourcePath` | Absolute path of that alias file; `null` only in the rare sourceless case |
| `command` | Non-interactive: the final command with placeholders resolved (arguments are already quoted for the shell, so it can go straight to `sh -c`); interactive: **the unresolved template** |
| `cwd` | Working directory the alias would run in (absolute) |
| `paths` | Directories actually prepended to `PATH` — see below |
| `mode` | `normal` / `interactive` / `silent` |
| `interactive` | Derived boolean for `mode == "interactive"`, kept for callers that only know the boolean |
| `description` | `$description`, or `null` |

Two fields deserve their own explanation, because a plugin's correctness rests on them:

* **`command` is a template when `mode` is `interactive`.** The placeholder values have to be asked of a human, and byk cannot answer for one without a terminal, so it returns `deploy --env {env}` untouched with `mode: "interactive"`. The caller either prompts itself or hands the request back to byk in a terminal; executing that string directly skips the confirmation.
* **`paths` is the effective value, not the configured one.** Entries are absolutised (relative ones against the alias file's directory), directories that do not exist are dropped, and the working directory's `node_modules/.bin` is included, along with the dependency directory's venv bin / `node_modules/.bin` when the file declares `$deps.pip` / `$deps.npm`. An entry written in the file but pointing nowhere will not appear.

```json title="byk __api__ resolve int"
{
  "key": "int",
  "source": "@i",
  "sourcePath": "/Users/you/proj/i.byk.json",
  "command": "deploy --env {env}",
  "cwd": "/Users/you/proj",
  "paths": ["/Users/you/proj/scripts", "/Users/you/proj/node_modules/.bin"],
  "mode": "interactive",
  "interactive": true,
  "description": null
}
```

## paths `[name]`

Called without a name it returns the directories plus the alias file list, for programs that want everything at once:

```json title="byk __api__ paths"
{
  "root": "/Users/you/.byk",
  "alias": "/Users/you/.byk/alias",
  "workdir": "/Users/you/proj",
  "aliasFiles": [
    "/Users/you/.byk/alias/ops.byk.json",
    "/Users/you/proj/run.byk.json"
  ]
}
```

| Field | Meaning |
|-------|---------|
| `root` | CLI root directory, the same as `${byk_dir}` inside aliases |
| `alias` | Global alias directory |
| `workdir` | Process working directory, where local alias files are looked up |
| `aliasFiles` | Absolute paths of alias files in both directories: global first, then local, each sorted by key; a directory used as both scopes is listed once; an empty array when there are none. Use `file --list` when you need key, scope, or directory |

The list is enumerated by filename only and content is never read: a file with broken JSON, a missing link target, or a broken symlink is still listed, and whether it is usable is `check`'s job; files with invalid names do not appear. Every value only answers "where is it" and **never creates anything**.

### Reading paths

Shell scripts use `paths <name>`: it prints that value as a bare string — no quotes, no label, a single trailing newline — exactly the shape `$()` wants. `<name>` accepts `root`, `alias`, or `workdir`, matching the JSON fields one-to-one.

```bash
INSTALL_DIR="$(byk __api__ paths root)/bin"
ALIAS_DIR="$(byk __api__ paths alias)"
WORKDIR="$(byk __api__ paths workdir)"
```

A wrong name lists the valid ones and exits 1:

```text
__api__ paths: unknown name "bin" (expected one of: root, alias, workdir)
```

`paths <name>` deliberately does not wrap its answer in JSON: its caller is a shell script, and wrapping would force `jq` or `sed` to strip the quotes, while `"$(...)"` gets a clean value for free. Programs that want structure call `paths` with no argument. The human-readable version is still `byk --paths` — labelled and spaced for reading in a terminal; it shares the same path layout and the same filename enumeration with argument-less `paths`, and differs only in shape.

## file `<file-key>` / `--list`

`file` has two forms: give it a file key to resolve an address, or add `--list` to list every alias file.

### A single key

Resolves a file key to an address without reading the file or requiring it to exist:

```bash
byk __api__ file @run
```

```json title="byk __api__ file @run"
{
  "key": "@run",
  "scope": "local",
  "path": "/Users/you/proj/run.byk.json",
  "dir": "/Users/you/proj"
}
```

It accepts the same key forms as file commands: `@name` (working directory), `@@name` (global alias directory), `@` / `@@` (the anonymous `.byk.json`). `path` matches an entry in `paths.aliasFiles`; `key`, `scope`, and `dir` come on top.

* **No existence check**: it answers "where would this land under byk's rules", the same path `@run..path` prints, plus `scope` and `dir`.
* **Address only, not content**: to learn which file an alias came from and what it finally runs, use `resolve`.
* **Links are not followed**: the result is the location of the link file itself, not its target.
* **Alias keys are rejected**: the dot in `@run.build` makes it an invalid filename, exiting 1.

### `--list`

With no key and `--list`, it returns every alias file, ordered like `paths.aliasFiles`: global first, then local, each sorted by key. Unlike `aliasFiles`, it keeps both scope identities, so a directory that serves as both scopes yields two entries. Every entry has the same shape as the single-key response.

```bash
byk __api__ file --list
```

```json title="byk __api__ file --list"
{
  "files": [
    {
      "key": "@@ops",
      "scope": "global",
      "path": "/Users/you/.byk/alias/ops.byk.json",
      "dir": "/Users/you/.byk/alias"
    },
    {
      "key": "@run",
      "scope": "local",
      "path": "/Users/you/proj/run.byk.json",
      "dir": "/Users/you/proj"
    }
  ]
}
```

The list is enumerated by filename only and content is never read: a file with broken JSON, a missing link target, or a broken symlink is still listed, while invalid filenames do not appear. `--list` cannot be combined with a key, and an unknown option also exits 1.

## expand `[--no-builtins] <path>`

Expands the variables in a JSON file and prints the result. The argument is an ordinary file path (a relative one is resolved against the process working directory), **not an `@file` key**. The flag comes before the path.

`--no-builtins` expands only the file's own `$var` declarations: `${byk_dir}`, `${work_dir}`, `${file_dir}` and `${deps_dir}` are not injected and stay as written unless `$var` declares a variable with that name.

```json title="./config.json"
{
  "$var": {
    "TOOLS": "${byk_dir}/tools"
  },
  "deploy": "cd ${file_dir} && ${TOOLS}/deploy.sh"
}
```

```bash
byk __api__ expand ./config.json
```

```json title="byk __api__ expand ./config.json"
{
  "deploy": "cd /Users/you/proj && /Users/you/.byk/tools/deploy.sh"
}
```

By default the rules match `..json --expand`:

* Expands `${byk_dir}`, `${work_dir}`, `${file_dir}`, and a top-level `$var`; `$var` may override a built-in name; `${deps_dir}` is additionally injected when the target sits inside the global alias directory
* Removes the top-level `$var` after expansion
* Unknown `${name}`, bare `$HOME`, and `\${...}` stay as-is; `${args}` is an alias placeholder and is not expanded
* **No alias-structure validation**: missing `$var`, missing `$cmd`, or even a non-object root are all fine as long as the JSON parses; built-ins expand unless `--no-builtins` is given
* Does not follow link arrays, apply inheritance, or execute anything

`--no-builtins` is available only on the `__api__` request (not on `..json --expand`): the four built-ins are left unset, while `$var` removal, name checks, and warnings behave exactly as above. A `$var` entry named after a built-in becomes an ordinary custom variable.

Problems with `$var` declarations (invalid names, self-references) only warn on stderr and the request still succeeds with a complete JSON document on stdout. Only an unreadable file, a directory, or invalid UTF-8/JSON exits 1 with an empty stdout.

## check

The machine form of `byk --check`: scans the working directory and the global alias directory — the same two places normal execution reads — and returns the problems found there.

```bash
byk __api__ check
```

```json title="byk __api__ check"
{
  "scanned": 2,
  "errors": 1,
  "warnings": 1,
  "items": [
    {
      "level": "error",
      "path": "/Users/you/proj/gone.byk.json",
      "message": "cannot load link target /Users/you/proj/missing.byk.json: cannot read file: No such file or directory (os error 2)"
    },
    {
      "level": "warning",
      "path": "/Users/you/proj/env.byk.json",
      "message": "$mode must be one of normal|interactive|silent, got \"activ\" (treated as normal)"
    }
  ]
}
```

| Field | Meaning |
|-------|---------|
| `scanned` | Number of candidate `*.byk.json` entries encountered, including invalid file names and broken symlinks |
| `errors` / `warnings` | Item counts, so a caller can badge without walking the list |
| `items[].level` | `error` (file or alias unusable) or `warning` (still usable, but suspicious) |
| `items[].path` | Absolute path of the file the problem belongs to |
| `items[].message` | Same text the human-readable report prints |

**Problems do not change the exit code.** The request succeeds as long as it ran, so stdout carries a complete payload and the caller reads `items` — only a usage error (an extra argument) exits 1. This keeps "there are problems" apart from "the request failed", which is also why the `__api__` exit-code rule above does not apply to findings.

The scan is not recursive, exactly like execution: it covers the process working directory plus the global alias directory, so an editor plugin runs one request per directory it wants covered.

## How completion hooks up

`install.sh` writes one line to `~/.zshrc` (or `~/.bashrc`):

```bash
# byk shell completion
if command -v byk >/dev/null 2>&1; then source <(byk __api__ completion zsh); fi
```

This line forwards Tab events to `byk __api__ complete`, which scans your aliases in real time and returns candidates. Writing the same line by hand works exactly the same.

## Versions and compatibility

Requests get added over time — `resolve`, `paths`, `file`, `expand` and `check` all arrived after the first release. When integrating:

* read request names from `byk __api__`, never hardcode the list
* tolerate unknown fields when parsing the JSON; fields only get added
* check `byk -v` first — a request the installed version lacks fails with exit code 1

***

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