For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /cli/file-commands.md.
  • English
  • File Commands

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

    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.

    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

    FormTarget file
    @ops..json./ops.byk.json in the current directory
    @@ops..json~/.byk/alias/ops.byk.json
    @..jsonanonymous file ./.byk.json
    @@..jsonanonymous 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

    CommandPurpose
    ..initCreate an empty alias file or a link file
    ..destroyDelete the alias file
    ..clearReset the file to {}
    ..setCreate or edit an alias, or file-level metadata
    ..removeDelete an alias or a whole group
    ..jsonPrint the file contents
    ..pathPrint the absolute file path
    ..renameRename the alias file
    ..cloneCopy a local or remote alias file
    ..linkTurn the current file into a link to another file
    ..depsInstall, uninstall, or inspect the file's declared dependencies
    ..helpShow commands, usage, and options

    Creating and Deleting

    ..init

    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

    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

    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

    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.

    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:

    OptionDescription
    --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-recursiveAllow / disallow re-entry on the call chain
    --private / --no-privateMove out of / back into the merged space
    --unset <fields>Remove metadata; combine cwd,mode,description,recursive

    File-root options (no key):

    OptionDescription
    --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-privateMove the whole file out of / back into the merged space
    --unset <fields>Remove metadata; combine priority,paths,cwd,mode
    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.
    • A key cannot start with $; use the options above for metadata instead of writing it into the key.

    ..remove

    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

    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

    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

    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

    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>

    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:

    SourceDescription
    @name / @@nameAn 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 / --githubRead from a GitHub repository
    -ge / --giteeRead from a Gitee repository
    -jd / --jsdelivrRead a GitHub file through jsDelivr
    -t / --tapResolve a key from a local or GitHub byk.tap.json
    -d / --depsAlso 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.
    ShorthandResult
    -gh user/repothe repository root .byk.json
    -gh user/repo@v1the repository root .byk.json on v1
    -gh user/repo@v1/tools/releasetools/release.byk.json
    -gh user/repo@v1/tools/tools/.byk.json
    -gh user/repo@v1/the repository root .byk.json

    Local path resolution:

    InputRead
    ./tools/release.byk.jsonas written
    ./tools/releasethe literal release first, then release.byk.json
    ./tools/, ., ..that directory's .byk.json (the anonymous file)
    ./config.json, ./hello.txtas 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.

    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:

    {
      "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)

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

    ..deps [install|uninstall|status]

    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:

    SituationAction
    Declared, missing on diskadd
    Declared, recorded, source changedupdate (re-download and swap atomically)
    Recorded but the file is gonerepair
    Only exec differschmod, no fetch
    Declared, not recorded, file already presentadopt: take over the existing file, no fetch
    Recorded but no longer declaredremove (plus empty parent directories)
    Identicalkeep, skipped
    $ 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:

    $ 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 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).