# File Commands

Every alias file carries a set of reserved commands for creating, editing, and inspecting the file itself:

```bash
byk @file..command [args...]     # current directory
byk @@file..command [args...]    # global directory ~/.byk/alias/
```

`..` is the reserved separator. A token that starts with `@` / `@@` and contains `..` is never treated as an alias, so `byk @@ops..set` always runs a file command instead of looking up an alias named `@@ops..set`.

```bash
byk @@ops..init                            # create ~/.byk/alias/ops.byk.json
byk @@ops..set build --cmd "pnpm build"    # add the build alias
byk @@ops..json                            # inspect the file
byk @@ops..help                            # list all file commands
```

## Addressing

| Form | Target file |
|------|-------------|
| `@ops..json` | `./ops.byk.json` in the current directory |
| `@@ops..json` | `~/.byk/alias/ops.byk.json` |
| `@..json` | anonymous file `./.byk.json` |
| `@@..json` | anonymous global file `~/.byk/alias/.byk.json` |

* A file name cannot contain `.`, `@`, `/`, or spaces; letters, digits, `-`, `_`, and CJK are allowed.
* The first `..` is the separator; the command name after it may only contain letters, digits, `-`, and `_`.
* Mutating commands only write the addressed file; sources of `clone`, `link`, and `init --link` are read-only.
* `..set` and `..remove` refuse to rewrite a link file (single-element array); edit the link target instead. `..clear` empties the link file itself.
* When a command that requires the file finds it missing but the other side (current or global directory) has a file with the same name, the error suggests switching the prefix; `..path` does not require the file to exist.
* Mutating commands print status to stderr; `json`, `path`, and `help` write data to stdout, so pipes and `$(...)` work as expected.

## Command Index

| Command | Purpose |
|---------|---------|
| `..init` | Create an empty alias file or a link file |
| `..destroy` | Delete the alias file |
| `..clear` | Reset the file to `{}` |
| `..set` | Create or edit an alias, or file-level metadata |
| `..remove` | Delete an alias or a whole group |
| `..json` | Print the file contents |
| `..path` | Print the absolute file path |
| `..rename` | Rename the alias file |
| `..clone` | Copy a local or remote alias file |
| `..link` | Turn the current file into a link to another file |
| `..deps` | Install, uninstall, or inspect the file's declared dependencies |
| `..help` | Show commands, usage, and options |

## Creating and Deleting

### `..init`

```bash
byk @@ops..init                      # create an empty file {}
byk @ops..init --link @shared        # link to ./shared.byk.json
```

* Contents are always `{}` plus a trailing newline; an existing file is never overwritten.
* `--link <source>` creates a **link file** (a single-element array) holding the source's canonical absolute path.
* The source may be `@name` (current directory), `@@name` (global directory), or a path (`~` expands, relative paths resolve from the current directory). It must be an existing object alias file; a link file is rejected because links support only one level.
* A bare local name is literal first and falls back to `.byk.json`; `.`, `..`, a trailing `/`, or a directory name reads that directory's `.byk.json` — the same local rules as `..clone`.
* Creating a global file creates `~/.byk/alias/` when it does not exist.

### `..destroy`

```bash
byk @@ops..destroy        # interactive confirmation
byk @@ops..destroy --yes  # skip confirmation
```

* Deletes the addressed file. Interactive confirmation asks you to type the file name; non-TTY environments must pass `--yes`.
* A symlink removes only the link itself, leaving its target untouched; directories are refused.
* For a global file, the dependency directory `~/.byk/deps/@@<file-name>` is removed along with it.

### `..clear`

```bash
byk @@ops..clear --yes
```

* Resets the file to `{}`. An already-empty file only reports `Already empty` and is left alone.
* Clearing a link file empties the link file itself; the target is untouched.
* Clearing a symlink is refused — use `..destroy` to remove the link.
* Like `..destroy`, non-TTY environments require `--yes`.

## Editing Aliases

### `..set`

```bash
byk @@ops..set <key> [options...]    # edit one alias
byk @@ops..set [options...]          # edit file-level metadata
```

The first argument that does not start with `-` is the alias key; dots express group paths, and missing intermediate groups are created automatically.

```bash
byk @@ops..set build --cmd "pnpm build"
byk @@ops..set web.deploy --cmd "deploy.sh" --cwd ./web --mode interactive
byk @@ops..set build --unset mode
```

Alias options:

| Option | Description |
|--------|-------------|
| `--cmd <command>` | Set the command; required when creating an alias |
| `--cwd <path>` | Working directory |
| `--mode <mode>` | `normal` / `interactive` / `silent` |
| `--description <text>` | Help-page description |
| `--recursive` / `--no-recursive` | Allow / disallow re-entry on the call chain |
| `--private` / `--no-private` | Move out of / back into the merged space |
| `--unset <fields>` | Remove metadata; combine `cwd,mode,description,recursive` |

File-root options (no key):

| Option | Description |
|--------|-------------|
| `--priority <n>` | Ordering priority; values below 0 are treated as 0 |
| `--paths <dir>` | Prepend a directory to PATH; repeatable, **replaces** the whole `$paths` list |
| `--cwd <path>` | File-level working directory |
| `--mode <mode>` | File-level execution mode |
| `--private` / `--no-private` | Move the whole file out of / back into the merged space |
| `--unset <fields>` | Remove metadata; combine `priority,paths,cwd,mode` |

```bash
byk @@ops..set --priority 10 --paths ./bin --paths ~/tools/bin --private
```

* Adding metadata to a string alias converts it to the `{ "$cmd": ... }` object form; removing the extra metadata folds it back to a string.
* `--private` is inheritable; `--no-private` writes `false` on a child to re-expose it inside a private group. See [Visibility](/cli/alias/config.md#visibility).
* A key cannot start with `$`; use the options above for metadata instead of writing it into the key.

### `..remove`

```bash
byk @@ops..remove build
byk @@ops..remove web.deploy
```

* Removes an alias or an entire subtree by dotted path.
* A group left with only `$` metadata is pruned as well.
* A missing key is an error, never a silent success.
* To remove a single metadata field, use `..set <key> --unset <fields>`.

## Inspecting

### `..json`

```bash
byk @@ops..json               # validate, then print raw bytes
byk @@ops..json --no-check    # print raw bytes without validation
byk @@ops..json --expand      # expand variables and pretty-print
```

* The default validates JSON but prints the **exact original bytes**: no reordering and no added newline.
* `--no-check` skips validation entirely and prints even invalid JSON.
* `--expand` expands built-in and file `$var` variables, removes `$var`, and pretty-prints; variable problems go to stderr.
* `--expand` and `--no-check` cannot be combined.
* A link file prints the array itself; the target is not followed.

### `..path`

```bash
byk @@ops..path
# /Users/me/.byk/alias/ops.byk.json
```

Prints the absolute path. The file does not need to exist, and the command takes no arguments.

### `..rename`

```bash
byk @@ops..rename tools
```

* Renames within the same scope (`@` only affects the current directory, `@@` only the global one).
* The new name follows the same file-name rules; an existing target is refused.
* For a link file, only the link file is renamed; its target is untouched.
* For a global file, the dependency directory `~/.byk/deps/@@<old-name>` is renamed to `@@<new-name>` along with the file, so `${deps_dir}` keeps pointing at the right place.

### `..help`

```bash
byk @@ops..help           # command index
byk @@ops..help set       # usage and options for set
```

An unknown command lists every available file command.

## Cloning and Linking

### `..clone <source>`

```bash
byk @@ops..clone @shared
byk @@ops..clone ~/src/tool.byk.json
byk @@ops..clone ~/src/tool               # resolved as tool.byk.json
byk @@ops..clone ./tools/release          # release.byk.json in a subdirectory
byk @@ops..clone ./tools/                 # tools/.byk.json
byk @@ops..clone .                        # the current directory's .byk.json
byk @@ops..clone https://example.com/tool.byk.json
byk @@ops..clone -gh user/repo                     # the repository root .byk.json
byk @@ops..clone -gh user/repo@main/tools/release.byk.json
byk @@ops..clone --tap user/repo/build            # resolve `build` from byk.tap.json
byk @@ops..clone -t user/repo@v1/build -d
byk @@ops..clone https://example.com/tool.byk.json -d   # install $deps in the same go
```

Sources:

| Source | Description |
|--------|-------------|
| `@name` / `@@name` | An alias file in the current / global directory |
| Path | `~` expands; relative paths resolve from the current directory; a bare name gets `.byk.json` |
| `http://` / `https://` | Fetched through external `curl` |
| `-gh` / `--github` | Read from a GitHub repository |
| `-ge` / `--gitee` | Read from a Gitee repository |
| `-jd` / `--jsdelivr` | Read a GitHub file through jsDelivr |
| `-t` / `--tap` | Resolve a key from a local or GitHub `byk.tap.json` |
| `-d` / `--deps` | Also install the cloned file's `$deps` |

Repository shorthand shape:

```
<user>/<repo>[@<ref>][/<path>]
```

* `@<ref>` is optional and defaults to `HEAD`.
* `<path>` is optional: leaving it out reads the repository root `.byk.json`, so `user/repo` equals `user/repo/`.
* A `<path>` pointing at a directory must end with `/`, meaning that directory's `.byk.json`.
* The last segment is the file name; the `.byk.json` suffix is optional.
* The sugar covers the whole path only: `user/repo/ss` still reads `ss.byk.json` and is never guessed to be a `ss/` directory.
* Don't include a host. `-gh github.com/user/repo` would be read as `user=github.com`, so it fails outright with a hint to write `user/repo`.

| Shorthand | Result |
|-----------|--------|
| `-gh user/repo` | the repository root `.byk.json` |
| `-gh user/repo@v1` | the repository root `.byk.json` on `v1` |
| `-gh user/repo@v1/tools/release` | `tools/release.byk.json` |
| `-gh user/repo@v1/tools/` | `tools/.byk.json` |
| `-gh user/repo@v1/` | the repository root `.byk.json` |

Local path resolution:

| Input | Read |
|-------|------|
| `./tools/release.byk.json` | as written |
| `./tools/release` | the literal `release` first, then `release.byk.json` |
| `./tools/`, `.`, `..` | that directory's `.byk.json` (the anonymous file) |
| `./config.json`, `./hello.txt` | as written; other extensions are never rewritten |

* A bare name is literal first: `./tool` reads `tool`, and only falls back to `tool.byk.json` when `tool` is missing. So both stay reachable when they coexist — writing `./tool.byk.json` always addresses the alias file.

* Only names that could legally be an alias file name get the suffix: `hello.txt` or `my tool` stay literal and are never probed as `hello.txt.byk.json`, which would not be a valid alias file name anyway.

* When a bare name resolves to a directory, that directory's `.byk.json` is read, so `./tools`, `./tools/` and `.` all address the anonymous file.

* `..link` and `..init --link` resolve sources exactly the same way.

* When nothing matches, the error lists every candidate: `Source not found: …` plus `Also tried: …`.

* The destination must not exist; `..clone` never overwrites.

* A local source is validated first: it must be a JSON object, and a link file (array) is rejected.

* The result is an independent copy with no relationship to the source. Use `..link` for a live reference.

* Aliases and groups marked `$clone: false` are dropped from the copy; marked groups keep children that re-expose themselves with `$clone: true`, and the tag never appears in the result. If nothing would remain, the clone is refused before writing. A copy that strips anything, or carries a tag at all, is re-serialised with keys sorted. `$private` does not affect cloning.

* Either source freezes `$deps.base` into an absolute address and prints `Recorded $deps.base = …`. The form follows the source: **remote** writes an absolute http(s) directory URL, **local** writes a local absolute directory path. The fill-in rules are identical — the source file's directory when absent, resolved against the source file when relative (`.` / `../` / `sub/dir`), kept as-is when already absolute with only the trailing `/` added.

* `$deps.base` is a best-effort anchor written by the program, not a portability guarantee. Each clone in a chain (`a ← b ← c`) re-freezes it, so the original source semantics can be lost. Don't hand-write it.

* Neither form crosses into the other: a remote source rejects a local-path `base` (`/x`, `C:/x`), which is why **an alias file taken from the network cannot read local files**; a local source keeps an absolute URL as-is, and those assets still come off the network.

* A `base` containing variables fails outright: a clone has no variable table, so `${CDN}` cannot be evaluated and guessing would bake a bogus address into the file. Writing it back re-serialises the whole document (keys sorted); files with neither `$deps` nor `$clone` stay byte-for-byte copies.

* Remote sources require `curl`; without it you get an install hint. A 404 reports `Remote source not found: <url>` with a hint to check the repository, ref, and path — a directory path missing its trailing `/` lands here too.

* Options may come before or after the source: `-gh user/repo@v1/tool -d` equals `-d -gh ...`.

#### Tap index (`--tap`)

A repository can publish many alias files without keeping them all at the root: `--tap` reads a routing table named `byk.tap.json` from the repository root.

```bash
git clone https://github.com/user/repo ~/.byk/tap/user/repo   # optional: byk only reads it
byk @@ops..clone --tap user/repo/build
byk @@ops..clone --tap build                      # search every local tap index
byk @@ops..clone -t user/repo@v1/build -d
```

The index is a flat JSON object. Keys starting with `$` are reserved for metadata and never match:

```json
{
  "build": "aliases/build.byk.json",
  "release": "https://example.com/other/tool.byk.json"
}
```

* Tap source shape: `<user>/<repo>[@<ref>]/<key>`. `<ref>` defaults to `HEAD`; `<key>` is exactly one path segment and cannot contain `/`, be `.` or `..`, or start with `$`.
* `--tap` is GitHub-only and is itself a source form: it cannot be combined with `-gh`, `-ge`, or `-jd`.
* **Local index first (full form).** Byk reads `~/.byk/tap/<user>/<repo>/byk.tap.json` when the spec has no `@<ref>`. When that file exists it is authoritative: parse errors, a missing key, a non-string entry, or a missing target all fail; only a missing index file falls back to GitHub. An explicit `@<ref>` always uses the remote index.
* **Single-key shorthand.** `--tap <key>` with no `/` searches every valid `~/.byk/tap/<user>/<repo>/byk.tap.json` without fetching an index from the network. A unique match is cloned from that local index (a URL value still uses the remote clone path); when several repositories contain the key, the command lists the full forms `user/repo/key` and asks you to pick one; when none contain it, the command fails without any remote fallback.
* The shorthand reads exactly two levels: `tap/<user>/<repo>/byk.tap.json`. Directory names must be valid GitHub usernames / repository names; invalid names and directories without an index are skipped. Unreadable or invalid indexes are reported as warnings and skipped, so uniqueness only covers readable indexes.
* The shorthand has no `@ref`; use the full form to pin a ref, which reads the remote index.
* `~/.byk/tap/` is a read-only cache: byk never creates, updates, or deletes it. Populate it yourself, for example `git clone https://github.com/user/repo ~/.byk/tap/user/repo`.
* Values are literal pointers; no `.byk.json` suffix is added and directories are not followed. A target starting with `@` or `@@` is a literal file name, never an alias reference.
  * Local index: a relative value resolves from the index's directory; absolute paths and `~` are local files; `http(s)` URLs still use the remote clone path.
  * Remote index: a relative value resolves from the repository root; only `http(s)` URLs and repository-relative paths are allowed, never local paths.
* Only one level is routed. The target must be an alias file, not another tap index: a target whose last segment is `byk.tap.json` is refused, and the resolved file is never followed as a second route.
* `$deps.base` is anchored on the target's location, not the index. A local target freezes it to a local absolute directory inside the cache; a URL target keeps the http(s) directory URL.
* A missing index reports `Tap index not found: …` with a hint to add `byk.tap.json`; a missing key lists the available keys.
* Byk prints which index it used before routing: `Tap index: local <path>` or `Tap index: remote <url>`, followed by `Tap <key> -> <target>`.

#### Clone and install dependencies (`-d`)

```bash
byk @@hello..clone https://example.com/hello.byk.json -d
```

* After the file lands, byk reads the new file's `$deps`: if present it runs the same sync as `..deps i` (a fresh key has no manifest, so it is a first install); if absent it is skipped rather than treated as an error.
* `-d` is global-only — dependency directories are keyed by the global file key, so a local destination is rejected before anything is downloaded.
* The install step never asks twice and needs no `--yes`: clone-to-assets-fetched is a single command, which suits scripts and non-interactive shells.
* A failed install does **not** roll back the clone: the file is already valid, so rerun `@@<file>..deps i` as suggested; assets already in place are never downloaded twice.

### `..link <target>`

```bash
byk @@ops..link @shared
```

* Rewrites the addressed file into a single-element array pointing at the target's canonical absolute path.
* Works only on an empty `{}` object or a file that is already a link; a non-empty alias file is refused.
* The target must be a local object alias file; a URL is rejected with a hint to use `..clone`. Local names follow the same rules as `..clone`: literal first, then `.byk.json`, with directories reading their `.byk.json`.
* Pointing at itself is refused, and symlinks are not rewritten.
* When the addressed file is missing, the error suggests `..init --link`.
* When retargeting a global file whose dependency directory already exists, byk suggests running `..deps uninstall` first so you keep using the old target's assets.
* For link behaviour, path resolution, and identity rules, see [Single Link](/cli/alias/config.md#single-link).

### `..deps [install|uninstall|status]`

```bash
byk @@tool..deps                       # current state: declared, present, missing, outdated, stale, unknown
byk @@tool..deps install               # sync files and install declared packages
byk @@tool..deps i                     # same, via an unambiguous prefix
byk @@tool..deps i --force             # ignore the manifest and re-download file entries
byk @@tool..deps uninstall             # delete the whole dependency directory (interactive confirmation)
byk @@tool..deps u                     # same; u / un / uni all work
byk @@tool..deps uninstall --yes       # skip the uninstall confirmation
```

The subcommand is one of `install` / `uninstall` / `status`, and unambiguous prefixes are accepted; no subcommand means `status`.

**install syncs, it does not append.** `$deps.files` is the desired state, and installing converges the directory to it:

| Situation | Action |
|-----------|--------|
| Declared, missing on disk | `add` |
| Declared, recorded, source changed | `update` (re-download and swap atomically) |
| Recorded but the file is gone | `repair` |
| Only `exec` differs | `chmod`, no fetch |
| Declared, not recorded, file already present | `adopt`: take over the existing file, no fetch |
| Recorded but no longer declared | `remove` (plus empty parent directories) |
| Identical | `keep`, skipped |

```bash
$ byk @@tool..deps i
Syncing 2 declared entries in ~/.byk/deps/@@tool:
  update  @@tool/bin/tool <- https://example.com/v2/tool
  keep    @@tool/etc/cfg.json
Downloaded 1 file into ~/.byk/deps/@@tool
```

When no file entry changed and no packages are declared, it is a no-op and never touches the network:

```bash
$ byk @@tool..deps i
@@tool: 2 declared, 2 present — up to date
```

* A relative `src` is joined with `$deps.base`; either one alone is an error, never a guess. `base` must be absolute on disk — the URL form means download, the local-path form means copy, and `..clone` picks it by source. Its relative forms only mean something at clone time. The program writes `base`; it is a best-effort anchor, not a portability guarantee, so don't hand-write it.
* Local entries are compared by source mtime: a newer source is reinstalled, a missing one fails with `cannot read` and its path instead of being skipped.
* Works for global and local files alike: global assets land in `~/.byk/deps/@@<file-name>/`, local ones in `<file-dir>/.byk/deps/@<file-name>/` with a self-ignoring `.gitignore` (`*`).
* The install manifest lives at `<dedicated directory>/.byk-deps.json` and records the last declaration plus where each asset landed. Deleting it just restarts the bookkeeping; the next install adopts whatever is already there.
* Only paths byk installed are ever removed: anything else in the directory is left alone with a warning.
* The install step never asks twice and needs no `--yes`; `--force` is the only option, for cases the manifest cannot detect (assets corrupted from outside).
* Absolute addresses are fetched with the system `curl`, local paths are copied with `fs::copy` (same temp-file-then-rename dance); extraction is delegated to the system `tar` on both paths, and a missing tool errors with an install hint. The summary says `Downloaded` either way and counts the local ones in parentheses (`Downloaded 3 files into … (1 local)`); a run with nothing local has no parentheses. `$deps.files` only fetches files; `$deps.pip` and `$deps.npm` are handed to pip / npm themselves and are not part of the file manifest.
* `$deps.pip` installs Python packages into `.venv` inside the dedicated directory: the venv is created with `python3` (`python` on Windows) when missing, then `pip install` runs. The venv's `bin` / `Scripts` is prepended to `PATH`; a missing Python fails with an install hint.
* `$deps.npm` installs npm packages into the dedicated directory: a minimal `package.json` (`byk-deps`, `private`) is written when absent, then `npm install` runs. `node_modules/.bin` is prepended to `PATH`; a missing npm fails with an install hint.
* Packages install on every run and are not tracked by `.byk-deps.json` — pip / npm decide what is current. `--force` only affects file entries, and removing a spec from the declaration does not uninstall it; `..deps uninstall` clears the whole directory. `files` is optional, so a declaration may contain only packages.
* Everything lands inside the dedicated directory (`~/.byk/deps/@@<file-name>/` globally, `<file-dir>/.byk/deps/@<file-name>/` locally). See [Dependencies](/cli/alias/config.md#dependencies) for the field reference.
* An `extract` entry lands on a directory and is marked `(extract)`; reinstalling replaces the whole directory, so files dropped from a newer archive never linger. Without `to` it unpacks into the dependency root, which only works as the sole entry (it replaces that whole directory):

```
Downloading 2 files into ~/.byk/deps/@@tool:
  add     @@tool/bin/tool <- https://example.com/cli-linux
  add     @@tool/dist <- https://example.com/tool-1.4.tar.gz (extract)
Downloaded 2 files into ~/.byk/deps/@@tool
```

* A mid-run failure does not roll back finished entries; the error lists what already landed this run, and the manifest is written to match, so rerunning continues where it stopped.
* uninstall deletes the whole dependency directory; a missing directory is an error. status is read-only and writes to stdout, so it pipes well:

```
@@tool: 6 declared, 2 present, 1 stale
  ok        @@tool/bin/tool
  missing   @@tool/etc/cfg.json
  outdated  @@tool/dist
  stale     @@tool/bin/old-tool
  ok        pip:click>=8.0
  unknown   pip:git+https://example.com/tool.git
  missing   npm:chalk
Base: https://example.com/releases/v1/
Deps directory: ~/.byk/deps/@@tool
Hint: run `byk @@tool..deps i` to install the missing assets
```

`unknown` marks a pip direct reference (URL / VCS): its package name cannot be determined locally, so byk reports it instead of guessing. Unknown entries count as neither present nor missing.

`--check` only validates the declaration itself: whether it parses, whether two entries collide on one target, whether a relative `src` has a `base`, and whether package entries are non-empty strings. It never looks at what is installed — missing or outdated assets are runtime state, reported by `..deps status`.

## Completion

File-command completion covers:

* file names after `@` / `@@`, and command names after `..`;
* options after a command (for example `..set --`);
* command names after `..help`;
* existing key paths after `..remove` (read from the target file; link files are not completed);
* source arguments for `..clone`, `..link`, and `..init --link` (alias files starting with `@`);
* subcommands after `..deps` (`install` / `uninstall` / `status`).

***

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